Registry / web-framework / moderngl-window

moderngl-window

library3.1.1pypypi✓ verified 85d ago

moderngl-window is a cross-platform helper library for ModernGL, simplifying window creation and resource loading for OpenGL applications. It provides a unified API over various windowing backends like Pyglet, GLFW, and SDL2. The library is actively maintained with frequent updates, currently at version 3.1.1, ensuring compatibility and introducing new features.

web-framework

pip install moderngl-window

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MODERNGL-WINDOW

moderngl-window

web-frameworkpythonv3.1.1

Install

5.6s avg

Import

561ms

Disk

166MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 5.63s

py 3.11

✓ —

✓ 5.15s

py 3.12

✓ —

✓ 5s

py 3.13

2/4 runs

py 3.9

✓ —

✓ 6.65s

166MB installed

● package 166MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mglw

✓ import moderngl_window as mglw

Standard alias for the main library module.

WindowConfig

✓ from moderngl_window import WindowConfig

✗ import moderngl_window.WindowConfig

WindowConfig is typically imported directly from the top-level package for clarity and brevity when extending.

This quickstart demonstrates creating a basic window by extending `moderngl_window.WindowConfig`. It sets up an OpenGL 3.3 context, specifies window dimensions and title, and provides a minimal `on_render` method to clear the screen with a red color. The `run()` method then starts the window's event loop.

import moderngl_window as mglw class MyWindow(mglw.WindowConfig): # Set OpenGL version (e.g., 3.3 for core profile) gl_version = (3, 3) # Set window size window_size = (1280, 720) # Set window title title = "Hello, moderngl-window!" # Optionally, specify a resource directory for shaders, textures etc. # resource_dir = Path(__file__).parent.resolve() / "resources" def __init__(self, **kwargs): super().__init__(**kwargs) # Any setup for ModernGL context or resources goes here print("ModernGL context initialized!") def on_render(self, time: float, frametime: float): # Clear the framebuffer with a color (e.g., red) self.ctx.clear(1.0, 0.0, 0.0, 1.0) # You can also implement other event handlers like on_key_event, on_mouse_press_event etc. if __name__ == '__main__': # Run the window config. This creates the window and starts the event loop. MyWindow.run()

Debug

Known issues

breakingAll callback methods (e.g., `render`, `resize`, `key_event`) were renamed with an `on_` prefix in version 3.0.0. Existing code using older versions will break if updated to 3.0.0 or later.

fix

Rename methods such as `render` to `on_render`, `resize` to `on_resize`, `key_event` to `on_key_event`, etc.

affects: >=3.0.0

gotchaResource loading methods (e.g., `load_program`, `load_texture_2d`) use relative paths by default. If resources are not found, ensure `resource_dir` is set correctly in `WindowConfig` or that resource paths are registered using `moderngl_window.resources`.

fix

Set `resource_dir = Path(__file__).parent / "resources"` in your `WindowConfig` subclass or explicitly register resource directories using `moderngl_window.resources.register_dir('path/to/my/resources')`.

affects: all

gotcha`moderngl-window` automatically handles ModernGL context creation and activation when using `WindowConfig`. Attempting to manually create and activate a context *within* a `WindowConfig` subclass might lead to unexpected behavior or redundant operations.

fix

Rely on `WindowConfig` to manage the OpenGL context (accessible via `self.ctx`). If explicit context control is needed, consider using `moderngl_window.create_window_from_settings()` or lower-level window APIs.

affects: all

Errors

Common errors & fixes

AttributeError: 'MyWindow' object has no attribute 'render'

Attempting to use old callback names (e.g., `render`) after upgrading to moderngl-window 3.0.0 or later.

fix

Rename the method `render` to `on_render`. Apply this `on_` prefix to all other callback methods like `resize`, `key_event`, etc.

ModuleNotFoundError: No module named 'moderngl'

The core `moderngl` library, a fundamental dependency, is not installed in the current environment.

fix

Install the `moderngl` library: `pip install moderngl`.

FileNotFoundError: Cannot find resource: 'my_shader.glsl' in any known resource directories

The `moderngl-window` resource loader cannot locate the specified file because the `resource_dir` is not set or the file path is incorrect.

fix

Ensure `self.resource_dir` is correctly set in your `WindowConfig` to point to the directory containing your resources, or provide an absolute path to `self.load_program()`/`self.load_texture_2d()`. For example, `resource_dir = Path(__file__).parent.resolve() / "resources"`.

Upgrade

Version history

3.1.1latest on PyPI · released Jan 19, 2025

Audit

Dependencies

modernglrequiredCore OpenGL context library that moderngl-window wraps.

pygletoptionalDefault windowing backend used if no other is specified. Automatically installed.

PillowoptionalUsed for loading 2D textures, texture arrays, and cube maps.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/moderngl/moderngl ↗

packagehttps://pypi.org/project/moderngl-window/ ↗

docshttps://moderngl-window.readthedocs.io ↗