Runtime Options

options = {'audio': ('xaudio2', 'directsound', 'openal', 'pulse', 'silent'), 'com_mta': False, 'debug_font': False, 'debug_gl': True, 'debug_gl_shaders': False, 'debug_gl_trace': False, 'debug_gl_trace_args': False, 'debug_graphics_batch': False, 'debug_input': False, 'debug_lib': False, 'debug_media': False, 'debug_texture': False, 'debug_trace': False, 'debug_trace_args': False, 'debug_trace_depth': 1, 'debug_trace_flush': True, 'debug_win32': False, 'debug_x11': False, 'dw_legacy_naming': False, 'headless': False, 'headless_device': 0, 'osx_alt_loop': False, 'search_local_libs': True, 'shadow_window': True, 'vsync': None, 'win32_disable_shaping': False, 'win32_disable_xinput': False, 'win32_gdi_font': False, 'xlib_fullscreen_override_redirect': False, 'xsync': True}

Global dict of pyglet options.

To change an option from its default, you must import pyglet before any sub-packages. For example:

import pyglet
pyglet.options['debug_gl'] = False

The default options can be overridden from the OS environment. The corresponding environment variable for each option key is prefaced by PYGLET_. For example, in Bash you can set the debug_gl option with:


For options requiring a tuple of values, separate each value with a comma.

The non-development options are:


A Sequence of valid audio modules names. They will be tried from first to last until either a driver loads or no entries remain. See Choosing the audio driver for more information.

Valid driver names are:

  • 'xaudio2', the Windows Xaudio2 audio module (Windows only)

  • 'directsound', the Windows DirectSound audio module (Windows only)

  • 'pulse', the PulseAudio module

    (Linux only, otherwise nearly ubiquitous. Limited features; use 'openal' for more.)

  • 'openal', the OpenAL audio module (A library may need to be installed on Windows and Linux)

  • 'silent', no audio


If True, prints the path of each dynamic library loaded.


If True, all calls to OpenGL functions are checked afterwards for errors using glGetError. This will severely impact performance, but provides useful exceptions at the point of failure. By default, this option is enabled if __debug__ is (i.e., if Python was not run with the -O option). It is disabled by default when pyglet is “frozen” within a py2exe or py2app library archive.


By default, pyglet creates a hidden window with a GL context when is imported. This allows resources to be loaded before the application window is created, and permits GL objects to be shared between windows even after they’ve been closed. You can disable the creation of the shadow window by setting this option to False.

Some OpenGL driver implementations may not support shared OpenGL contexts and may require disabling the shadow window (and all resources must be loaded after the window using them was created). Recommended for advanced developers only.

New in version 1.1.


If set, the pyglet.window.Window.vsync property is ignored, and this option overrides it (to either force vsync on or off). If unset, or set to None, the pyglet.window.Window.vsync property behaves as documented.


If set (the default), pyglet will attempt to synchronise the drawing of double-buffered windows to the border updates of the X11 window manager. This improves the appearance of the window during resize operations. This option only affects double-buffered windows on X11 servers supporting the Xsync extension with a window manager that implements the _NET_WM_SYNC_REQUEST protocol.

New in version 1.1.


If False, pyglet won’t try to search for libraries in the script directory and its lib subdirectory. This is useful to load a local library instead of the system installed version. This option is set to True by default.

New in version 1.2.

Environment settings

Options in the pyglet.options dictionary can have defaults set through the operating system’s environment variable. The following table shows which environment variable is used for each option:

Environment variable

pyglet.options key


Default value



List of strings





1 [1]