Debugging tools

pyglet includes a number of debug paths that can be enabled during or before application startup. These were primarily developed to aid in debugging pyglet itself, however some of them may also prove useful for understanding and debugging pyglet applications.

Each debug option is a key in the pyglet.options dictionary. Options can be set directly on the dictionary before any other modules are imported:

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

They can also be set with environment variables before pyglet is imported. The corresponding environment variable for each option is the string PYGLET_ prefixed to the uppercase option key. For example, the environment variable for debug_gl is PYGLET_DEBUG_GL. Boolean options are set or unset with 1 and 0 values.

A summary of the debug environment variables appears in the table below.

Option Environment variable Type
debug_font PYGLET_DEBUG_FONT bool
debug_gl PYGLET_DEBUG_GL bool
debug_gl_trace PYGLET_DEBUG_GL_TRACE bool
debug_gl_trace_args PYGLET_DEBUG_GL_TRACE_ARGS bool
debug_graphics_batch PYGLET_DEBUG_GRAPHICS_BATCH bool
debug_lib PYGLET_DEBUG_LIB bool
debug_media PYGLET_DEBUG_MEDIA bool
debug_trace PYGLET_DEBUG_TRACE bool
debug_trace_args PYGLET_DEBUG_TRACE_ARGS bool
debug_trace_depth PYGLET_DEBUG_TRACE_DEPTH int
debug_win32 PYGLET_DEBUG_WIN32 bool
debug_x11 PYGLET_DEBUG_X11 bool

The debug_media and debug_font options are used to debug the and pyglet.font modules, respectively. Their behaviour is platform-dependent and useful only for pyglet developers.

The remaining debug options are detailed below.

Debugging OpenGL

The debug_graphics_batch option causes all Batch objects to dump their rendering tree to standard output before drawing, after any change (so two drawings of the same tree will only dump once). This is useful to debug applications making use of Group and Batch rendering.

Error checking

The debug_gl option intercepts most OpenGL calls and calls glGetError afterwards (it only does this where such a call would be legal). If an error is reported, an exception is raised immediately.

This option is enabled by default unless the -O flag (optimisation) is given to Python, or the script is running from within a py2exe or py2app package.


The debug_gl_trace option causes all OpenGL functions called to be dumped to standard out. When combined with debug_gl_trace_args, the arguments given to each function are also printed (they are abbreviated if necessary to avoid dumping large amounts of buffer data).

Tracing execution

The debug_trace option enables Python-wide function tracing. This causes every function call to be printed to standard out. Due to the large number of function calls required just to initialise pyglet, it is recommended to redirect standard output to a file when using this option.

The debug_trace_args option additionally prints the arguments to each function call.

When debug_trace_depth is greater than 1 the caller(s) of each function (and their arguments, if debug_trace_args is set) are also printed. Each caller is indented beneath the callee. The default depth is 1, specifying that no callers are printed.

Platform-specific debugging

The debug_lib option causes the path of each loaded library to be printed to standard out. This is performed by the undocumented pyglet.lib module, which on Linux and Mac OS X must sometimes follow complex procedures to find the correct library. On Windows not all libraries are loaded via this module, so they will not be printed (however, loading Windows DLLs is sufficiently simple that there is little need for this information).


X11 errors are caught by pyglet and suppressed, as there are plenty of X servers in the wild that generate errors that can be safely ignored. The debug_x11 option causes these errors to be dumped to standard out, along with a traceback of the Python stack (this may or may not correspond to the error, depending on whether or not it was reported asynchronously).


The debug_win32 option causes all library calls into user32.dll, kernel32.dll and gdi32.dll to be intercepted. Before each library call SetLastError(0) is called, and afterwards GetLastError() is called. Any errors discovered are written to a file named debug_win32.log. Note that an error is only valid if the function called returned an error code, but the interception function does not check this.