{"id":2518,"library":"glfw","title":"Python Bindings for GLFW","description":"glfw (pyGLFW) is a ctypes-based wrapper for GLFW3, a cross-platform library for OpenGL, OpenGL ES and Vulkan development. It simplifies window creation, context management, and input handling in Python, providing a near one-to-one mapping to the C API with Pythonic naming conventions. The current version is 2.10.0, and it maintains an active release cadence with regular updates.","status":"active","version":"2.10.0","language":"en","source_language":"en","source_url":"https://github.com/FlorianRhiem/pyGLFW","tags":["graphics","opengl","vulkan","windowing","gui","ctypes","game-development"],"install":[{"cmd":"pip install glfw","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"glfw is a Python binding for the native GLFW C library. While pre-compiled shared libraries are often bundled in Python wheels for Windows, macOS, and Linux, manual installation of the GLFW C library may be required on some systems or for specific configurations (e.g., via system package manager like 'apt install libglfw3' or by compiling from source).","package":"GLFW (C library)","optional":false},{"reason":"Commonly used in conjunction with glfw for rendering, as glfw only handles windowing and input, not graphics rendering itself.","package":"PyOpenGL","optional":true}],"imports":[{"note":"The modern pyGLFW API removes the 'glfw' and 'GLFW_' prefixes and uses snake_case for functions and constants (e.g., `glfw.init()` instead of `glfwInit()`, `glfw.KEY_ESCAPE` instead of `GLFW_KEY_ESCAPE`). Direct `from glfw.GLFW import *` is an older pattern or for strict C API adherence.","wrong":"from glfw.GLFW import *","symbol":"glfw","correct":"import glfw"}],"quickstart":{"code":"import glfw\nimport OpenGL.GL as gl\n\ndef main():\n    # Initialize the library\n    if not glfw.init():\n        raise RuntimeError(\"Failed to initialize GLFW\")\n\n    # Create a windowed mode window and its OpenGL context\n    window = glfw.create_window(640, 480, \"Hello pyGLFW\", None, None)\n    if not window:\n        glfw.terminate()\n        raise RuntimeError(\"Failed to create GLFW window\")\n\n    # Make the window's context current\n    glfw.make_context_current(window)\n\n    # Set viewport and clear color\n    gl.glViewport(0, 0, 640, 480)\n    gl.glClearColor(0.2, 0.3, 0.4, 1.0)\n\n    # Loop until the user closes the window\n    while not glfw.window_should_close(window):\n        # Render here\n        gl.glClear(gl.GL_COLOR_BUFFER_BIT)\n\n        # Swap front and back buffers\n        glfw.swap_buffers(window)\n\n        # Poll for and process events\n        glfw.poll_events()\n\n    glfw.terminate()\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart initializes GLFW, creates a basic window, sets up an OpenGL rendering context, and runs a simple event loop. It clears the window with a solid color until the user closes it. For actual rendering, you would integrate OpenGL (as shown with `OpenGL.GL`) or Vulkan commands within the main loop."},"warnings":[{"fix":"Refactor calls to use `glfw.snake_case_function_name()` and `glfw.CONSTANT_NAME`.","message":"The pyGLFW API (current 'glfw' PyPI package) translates GLFW C functions from `camelCase` with a `glfw` prefix (e.g., `glfwGetVersion`) to Pythonic `snake_case` without the prefix (e.g., `glfw.get_version()`). Similarly, constants like `GLFW_KEY_ESCAPE` become `glfw.KEY_ESCAPE`. Code written for the direct C API or older Python wrappers will need adaptation.","severity":"breaking","affected_versions":"All versions (since the project's inception for GLFW3 bindings)"},{"fix":"Ensure the native GLFW C library is correctly installed and accessible on your system's library search paths. Environment variables like `PYGLFW_LIBRARY` can be set to point to a specific library path, and `PYGLFW_LIBRARY_VARIANT` (e.g., 'wayland' or 'x11') can be used on Linux to explicitly select the variant.","message":"Despite Python wheels often including the GLFW C shared library for convenience (Windows, macOS, Linux), an `ImportError: Failed to load GLFW3 shared library` can occur. This usually means the native GLFW C library is not found or is incompatible. Users might need to install it via their system's package manager (e.g., `sudo apt install libglfw3 libglfw3-dev` on Debian/Ubuntu, `brew install glfw` on macOS) or compile it from source, ensuring the shared library is discoverable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `glfw>=2.8.0` to ensure proper bundling of GLFW 3.4, or manually install a compatible GLFW 3.4+ C library on version 2.7.0.","message":"Version `2.7.0` included GLFW 3.4 functions in the Python wrapper but explicitly noted that GLFW 3.4 was *not* included in Python wheels due to build issues on various systems (e.g., manylinux 2014). This could lead to unexpected behavior or missing functionality if a user expected bundled GLFW 3.4 features. This was resolved in `2.8.0` with an update to GLFW 3.4.","severity":"gotcha","affected_versions":"2.7.0"},{"fix":"Explicitly set the `PYGLFW_LIBRARY` environment variable to the path of the GLFW shared library within your frozen executable's distribution, or ensure the library is placed in a location where `glfw`'s internal search mechanism can find it (e.g., next to the executable).","message":"When distributing applications with tools like cx_Freeze or PyInstaller, `glfw` might struggle to locate the bundled GLFW shared library, especially on non-Windows platforms. While `glfw` has built-in search logic for frozen executables, custom setups might still fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}