Runtime Options

Pyglet offers a way to change runtime behavior through options. These options provide ways to modify specific modules, behavior for specific operating systems, or adding more debugging information. Options can be specified as a key, or as an attribute with the pyglet.options dataclass instance.

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

For example:

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

The default options can be overridden from the OS environment as well. 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.

class Options

Dataclass for global pyglet options.

audio: tuple = ('xaudio2', 'directsound', 'openal', 'pulse', 'silent')

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

com_mta: bool = False

If True, this will enforce COM Multithreaded Apartment Mode for Windows applications. By default, pyglet has opted to go for Single-Threaded Apartment (STA) for compatibility reasons. Many other third party libraries used with Python explicitly set STA. However, Windows recommends MTA with a lot of their API’s such as Windows Media Foundation (WMF).


New in version 2.0.5.

debug_font: bool = False

If True, will print more verbose information when Font’s are loaded.

debug_gl: bool = True

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 enabled (i.e., if Python was not run with the -O option). It is disabled by default when pyglet is “frozen”, such as within pyinstaller or nuitka.

debug_gl_shaders: bool = False

If True, prints shader compilation information such as creation and deletion of shader’s. Also includes information on shader ID’s, attributes, and uniforms.

debug_gl_trace: bool = False

If True, will print the names of OpenGL calls being executed. For example, glBlendFunc

debug_gl_trace_args: bool = False

If True, in addition to printing the names of OpenGL calls, it will also print the arguments passed into those calls. For example, glBlendFunc(770, 771)


Requires debug_gl_trace to be enabled.

debug_graphics_batch: bool = False

If True, prints batch information being drawn, including Group’s, VertexDomains, and Texture information. This can be useful to see how many Group’s are being consolidated.

debug_input: bool = False

If True, prints information on input devices such as controllers, tablets, and more.

debug_lib: bool = False

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

debug_media: bool = False

If True, prints more detailed media information for audio codecs and drivers. Will be very verbose.

debug_texture: bool = False

If True, prints information on Texture size (in bytes) when they are allocated and deleted.

debug_win32: bool = False

If True, prints error messages related to Windows library calls. Usually get’s information from Kernel32.GetLastError. This information is output to a file called debug_win32.log.

debug_x11: bool = False

If True, prints information related to Linux X11 calls. This can potentially help narrow down driver or operating system issues.

dw_legacy_naming: bool = False

If True, will enable legacy naming support for the default Windows font renderer (DirectWrite). Attempt to parse fonts by the passed name, to best match legacy RBIZ naming.


For example, this allows specifying "Arial Narrow" rather than "Arial" with a "condensed" stretch or "Arial Black" instead of "Arial" with a weight of black. This may enhance naming compatibility cross-platform for select fonts as older font renderers went by this naming scheme.

Starts by parsing the string for any known style names, and searches all font collections for a matching RBIZ name. If a perfect match is not found, it will choose a second best match.


Due to the high variation of styles and limited capability of some fonts, there is no guarantee the second closest match will be exactly what the user wants.


The debug_font option can provide information on what settings are being selected.

New in version 2.0.3.

headless: bool = False

If True, visible Windows are not created and a running desktop environment is not required. This option is useful when running pyglet on a headless server, or compute cluster. OpenGL drivers with EGL support are required for this mode.

headless_device: int = 0

If using headless mode (pyglet.options['headless'] = True), this option allows you to set which GPU to use. This is only useful on multi-GPU systems.

osx_alt_loop: bool = False

If True, this will enable an alternative loop for Mac OSX. This is enforced for all ARM64 architecture Mac’s.

Due to various issues with the ctypes interface with Objective C, Python, and Mac ARM64 processors, the standard event loop eventually starts breaking down to where inputs are either missed or delayed. Even on Intel based Mac’s other odd behavior can be seen with the standard event loop such as randomly crashing from events.

New in version 2.0.5.

search_local_libs: bool = True

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.

shadow_window: bool = True

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.

vsync: bool = None

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.

win32_disable_shaping: bool = False

If True, will disable the shaping process for the default Windows font renderer to offer a performance speed up. If your font is simple, monospaced, or you require no advanced OpenType features, this option may be useful. You can try enabling this to see if there is any impact on clarity for your font. The advance will be determined by the glyph width.


Shaping is the process of determining which character glyphs to use and specific placements of those glyphs when given a full string of characters.

New in version 2.0.

win32_disable_xinput: bool = False

If True, this will disable the XInput controller usage in Windows and fallback to DirectInput. Can be useful for debugging or special uses cases. A controller can only be controlled by either XInput or DirectInput, not both.

New in version 2.0.

win32_gdi_font: bool = False

If True, pyglet will fallback to the legacy GDIPlus font renderer for Windows. This may provide better font compatibility for older fonts. The legacy renderer does not support shaping, colored fonts, substitutions, or other OpenType features. It may also have issues with certain languages.

Due to those lack of features, it can potentially be more performant.

New in version 2.0.

xlib_fullscreen_override_redirect: bool = False

If True, pass the xlib.CWOverrideRedirect flag when creating a fullscreen window. This option is generally not necessary anymore and is considered deprecated.

xsync: bool = True

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.

options = Options(audio=('xaudio2', 'directsound', 'openal', 'pulse', 'silent'), debug_font=False, debug_gl=True, debug_gl_trace=False, debug_gl_trace_args=False, debug_gl_shaders=False, debug_graphics_batch=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_input=False, debug_x11=False, shadow_window=True, vsync=None, xsync=True, xlib_fullscreen_override_redirect=False, search_local_libs=True, win32_gdi_font=False, headless=False, headless_device=0, win32_disable_shaping=False, dw_legacy_naming=False, win32_disable_xinput=False, com_mta=False, osx_alt_loop=False)

Instance of Options used to set runtime options.

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]