{"id":4191,"library":"pyglet","title":"Pyglet","description":"Pyglet is a cross-platform windowing and multimedia library for Python, designed for developing games and other visually rich applications. It provides robust support for windowing, input event handling (keyboard, mouse, controllers), OpenGL graphics, loading various image and video formats, and playing sounds and music. Compatible with Windows, macOS, and Linux, pyglet is currently at version 2.1.14 and maintains an active development cycle with periodic updates and new releases.","status":"active","version":"2.1.14","language":"python","source_language":"en","source_url":"https://github.com/pyglet/pyglet","tags":["game development","multimedia","graphics","windowing","opengl"],"install":[{"cmd":"pip install pyglet","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Optional dependency for playing a wide variety of compressed audio (MP3, OGG/Vorbis, WMA) and video (MPEG2, H.264, H.265, WMV, Xvid) formats. Built-in support exists for basic formats (wav, png, bmp) without FFmpeg.","package":"FFmpeg","optional":true}],"imports":[{"symbol":"pyglet","correct":"import pyglet"},{"note":"While 'import pyglet' and accessing as pyglet.window.Window() works, explicit import is common for brevity.","wrong":"import pyglet.window as window; window.Window()","symbol":"Window","correct":"from pyglet.window import Window"},{"symbol":"run","correct":"pyglet.app.run()"},{"symbol":"schedule_interval","correct":"pyglet.clock.schedule_interval(func, interval)"}],"quickstart":{"code":"import pyglet\n\nwindow = pyglet.window.Window(800, 600, caption='Hello Pyglet')\nlabel = pyglet.text.Label('Hello, world', font_name='Times New Roman', font_size=36,\n                          x=window.width//2, y=window.height//2,\n                          anchor_x='center', anchor_y='center')\n\n@window.event\ndef on_draw():\n    window.clear()\n    label.draw()\n\npyglet.app.run()","lang":"python","description":"This minimal example opens an 800x600 pixel window displaying 'Hello, world!' centered. It demonstrates window creation, text rendering, event handling via decorator, and starting the application loop."},"warnings":[{"fix":"Review and update OpenGL code to utilize modern OpenGL (3.3+) practices. Consult the 'Migrating from pyglet 1.5' guide in the official documentation.","message":"Pyglet 2.0 (and later) requires modern OpenGL (3.3+) context, moving away from legacy OpenGL 2.0. Applications making direct OpenGL 1.x API calls or using older shaders will need significant updates.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Refer to the 'Migrating from pyglet 2.0' guide in the official documentation for specific changes and updated API usage.","message":"Pyglet 2.1 introduced minor breaking changes to arguments for text, UI, and game controller handling. Locations/names for some features, data types, and math classes (e.g., `pyglet.math.Mat3` and `Mat4` now accept direct arguments instead of an iterable) also changed. The `pyglet.options` module is now accessed as a `pyglet.options` attribute.","severity":"breaking","affected_versions":"2.1.0 and later"},{"fix":"Install FFmpeg on your operating system (e.g., via a package manager like `apt`, `brew`, or by downloading binaries) if you need to play advanced media formats.","message":"To play a wide range of compressed audio (e.g., MP3, OGG/Vorbis, WMA) and video formats (e.g., MPEG2, H.264), FFmpeg must be installed separately on your system. Without it, only basic formats (like WAV, PNG, BMP) are supported.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your scheduled function signature includes `dt`, e.g., `def update(dt): ...`.","message":"When using `pyglet.clock.schedule_interval()` to schedule a function to run periodically, the scheduled function MUST accept a `dt` (delta time) parameter as its first argument, even if the value is not used within the function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always include `window.clear()` as the first line within your `on_draw` function.","message":"Forgetting to call `window.clear()` at the beginning of your `on_draw` event handler will result in drawing artifacts from previous frames, as the buffer is not explicitly cleared.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.1.14':59 'activ':63 'applic':22 'compat':48 'control':34 'cross':6 'cross-platform':5 'current':56 'cycl':65 'design':14 'develop':16,64,73 'event':30 'format':42 'game':17,72 'graphic':36,75 'handl':31 'imag':39 'input':29 'keyboard':32 'librari':11 'linux':53 'load':37 'maco':51 'maintain':61 'mous':33 'multimedia':10,74 'music':47 'new':70 'opengl':35,77 'period':67 'platform':7 'play':44 'provid':24 'pyglet':1,2,54 'python':13 'releas':71 'rich':21 'robust':25 'sound':45 'support':26 'updat':68 'various':38 'version':58 'video':41 'visual':20 'window':8,28,50,76","created_at":"2026-04-12T03:44:50.662966+00:00","updated_at":"2026-04-16T18:28:18.893054+00:00","problems":[{"fix":"Ensure pyglet is installed correctly for your Python environment: `pip install pyglet` (or `pip3 install pyglet` for Python 3 specific installations). If using a virtual environment or IDE, ensure it's activated and configured to use the correct Python interpreter where pyglet is installed.","cause":"The pyglet library is not installed in the Python environment being used, or the Python interpreter cannot find the installed package.","error":"ModuleNotFoundError: No module named 'pyglet'"},{"fix":"Rename your Python script file to something other than `pyglet.py` (or any other pyglet module name like `window.py`, `gl.py`). For API changes, consult the pyglet documentation for the version you are using (e.g., `pyglet.window.Window` for creating a window, `pyglet.resource.image` for loading images, `pyglet.media.load` for loading audio/video).","cause":"This typically happens when your Python script file is named `pyglet.py` (or `window.py`, `gl.py`, etc.), causing Python to import your local script instead of the actual pyglet library. It can also occur if attempting to access attributes or functions that have been moved or deprecated in newer pyglet versions without importing the specific submodule, e.g., `pyglet.window.Window()` instead of `from pyglet import window; window.Window()` or `from pyglet.window import Window; Window()`. Or for `pyglet.load` instead of `pyglet.resource.image()` for images or `pyglet.media.load()` for media.","error":"AttributeError: module 'pyglet' has no attribute 'window' (or 'text', 'gl', 'media', 'load')"},{"fix":"Install the necessary OpenGL development libraries for your operating system. For Debian/Ubuntu-based systems, this often involves `sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev`. For other systems, refer to their package managers for OpenGL development packages.","cause":"pyglet relies on OpenGL (GL) and GLU libraries being present on your system. This error indicates that these underlying graphics libraries are missing or cannot be found by pyglet, often encountered on Linux systems or in Docker containers without proper graphics library installations.","error":"ImportError: Library \"GL\" not found"},{"fix":"Ensure `pyglet.app.run()` is called at the end of your main script after setting up your window and event handlers. This starts the main event loop. For example: `import pyglet; from pyglet.window import Window; window = Window(); @window.event def on_draw(): pass; pyglet.app.run()`.","cause":"The pyglet event loop, `pyglet.app.run()`, was not called or was called incorrectly. This function is essential for starting the application's event processing, keeping the window open, and making it responsive to user input and drawing events. Without it, the program will execute and terminate, closing the window immediately, or the window will become unresponsive.","error":"Pyglet window appears briefly and closes / Window not responding / Program exits without showing window"},{"fix":"If using a codebase designed for `pyglet 1.x`, downgrade your pyglet installation to a compatible version (e.g., `pip install pyglet==1.5.27`). Alternatively, update your code to use the `pyglet 2.x` API, which might involve importing constants from different submodules or using more modern OpenGL approaches (e.g., shaders instead of immediate mode functions like `GL_LIGHTING`).","cause":"This error frequently arises when using code written for older versions of pyglet (specifically `pyglet 1.x`) with a newer `pyglet 2.x` installation. Many OpenGL constants and functions were reorganized or deprecated in `pyglet 2.x` to align with modern OpenGL practices.","error":"ImportError: cannot import name 'GL_LIGHTING' from 'pyglet.gl'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.16","cli_name":"","cli_version":null,"type":"library","homepage":"https://pyglet.org","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/pyglet/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}