moderngl

library5.12.0pypypi✓ verified 91d ago

ModernGL is a high-performance Python wrapper over OpenGL Core, simplifying the creation of graphics applications like scientific simulations, games, or user interfaces. It aims to provide a more Pythonic and less boilerplate-heavy API compared to direct OpenGL bindings like PyOpenGL. The current stable version is 5.12.0, with releases occurring periodically, often including breaking changes.

http-networking

pip install moderngl

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MODERNGL

moderngl

http-networkingpythonv5.12.0

Install

1.7s avg

Import

16ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.12.0 · 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

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.017s · 22.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.016s · 20MB

19MB installed

● package 19MB

Code

Verified usage

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

moderngl

✓ import moderngl

create_context

✓ from moderngl import create_context

get_context

✓ from moderngl import get_context

BLEND

✓ ctx.BLEND

✗ moderngl.BLEND

Constants like BLEND, DEPTH_TEST, etc., were moved from the top-level module to the Context object in version 5.9.0.

This quickstart demonstrates creating a ModernGL context (headless in this example), allocating a buffer on the GPU, writing data to it, and reading it back. For graphical applications, `moderngl.create_context()` would typically be called after setting up a window with an OpenGL-capable library.

import moderngl # Create a headless context or attach to an existing one # For a windowed application, ctx = moderngl.create_context() # after a window is created by a library like Pygame, GLFW, etc. ctx = moderngl.create_context(standalone=True) # Create a buffer on the GPU buf = ctx.buffer(b"Hello ModernGL World!") # Read data back from the buffer print(buf.read()) # Release resources (important for standalone contexts) # For windowed contexts, resource management is often handled by the windowing library. ctx.release()

Debug

Known issues

breakingPython 3.7 support was removed in ModernGL 5.9.0. Ensure your environment uses Python 3.8 or newer.

fix

Upgrade Python to version 3.8 or higher.

affects: >=5.9.0

breakingGlobal constants (e.g., `moderngl.BLEND`, `moderngl.DEPTH_TEST`, `moderngl.CULL_FACE`) were moved to the `Context` object in version 5.9.0. Direct access to these from the `moderngl` module will raise an `AttributeError`.

fix

Access these constants directly from the `Context` instance, e.g., `ctx.BLEND` instead of `moderngl.BLEND`.

affects: >=5.9.0

gotchaModernGL context creation (`moderngl.create_context()`) requires an existing OpenGL context (e.g., from a windowing library) or the `standalone=True` flag for headless rendering. Incorrect setup is a common source of errors.

fix

If integrating with a window, ensure `create_context()` is called after the window's OpenGL context is active. For headless use, always pass `standalone=True`. Consider `moderngl-window` for simplified window management.

affects: All

gotchaShader compilation errors, especially with compute shaders, can sometimes lead to silent crashes without clear Python exceptions. This can be due to insufficient OpenGL version support or driver issues.

fix

When creating a context, explicitly require the necessary OpenGL version, e.g., `ctx = moderngl.create_context(standalone=True, require=430)` for compute shaders. Check shader source for syntax errors.

affects: All

gotchaOpenGL resources (buffers, textures, programs) should be created once during initialization and reused. Creating them repeatedly (e.g., in a rendering loop) leads to severe performance degradation and memory leaks.

fix

Allocate all ModernGL objects at program startup or when resources are first needed, and store references for reuse. Release them when no longer required or at program termination.

affects: All

gotchaWhen rendering transparent objects with depth testing and blending enabled, objects must be drawn in a specific order (typically back-to-front relative to the camera) to ensure correct blending results. Incorrect order leads to visual artifacts.

fix

Sort transparent objects by depth before rendering. Consider alternative blending techniques if sorting is not feasible for complex scenes.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'moderngl'

The 'moderngl' package is either not installed in the current Python environment, or there's a capitalization mismatch in the import statement.

fix

Install the library using `pip install moderngl` and ensure the import statement uses lowercase: `import moderngl`.

AttributeError: module 'moderngl' has no attribute 'create_context'

This error often indicates a version incompatibility, specifically when transitioning from older ModernGL versions (e.g., ModernGL4) where the module might have been capitalized, or if global constants like `moderngl.BLEND` are accessed directly instead of through the context object.

fix

Ensure you are using the correct `moderngl` (lowercase) import and are accessing `create_context` directly from `moderngl`. For constants, access them via a created context object, e.g., `ctx.BLEND` instead of `moderngl.BLEND`.

Exception: cannot detect OpenGL context

ModernGL requires an active OpenGL context to perform operations. This error occurs when `moderngl.create_context()` is called without an existing OpenGL context (e.g., from a windowing library like Pygame or GLFW) being active, or when attempting headless rendering without specifying `standalone=True`.

fix

If using a windowing library, ensure its OpenGL context is created and active before calling `moderngl.create_context()`. For headless rendering, create a standalone context: `ctx = moderngl.create_context(standalone=True)`.

moderngl.error.Error: GLSL Compiler failed

This error signals a problem within the GLSL shader code itself, such as syntax errors, attempting to use an OpenGL Shading Language version not supported by the system's graphics drivers, or issues with shader linking.

fix

Thoroughly review your GLSL shader code for any syntax errors. Verify that the `#version` directive in your shader (e.g., `#version 330`) is supported by your system's OpenGL drivers. You might need to explicitly request a specific OpenGL version when creating the context, for example: `ctx = moderngl.create_context(require=430)`.

moderngl.error.Error: content[0][3] must be an attribute not NoneType

GLSL compilers often optimize out (remove) shader attributes or uniforms that are declared but not actively used within the shader's logic. When ModernGL then tries to bind data to these optimized-out variables, it cannot find them, leading to this error.

fix

Ensure that every attribute and uniform declared in your GLSL shader code is actually used somewhere in the shader's computations or output. If an attribute or uniform is optional, either make sure it has a usage path in the shader or handle its potential absence gracefully in your Python code.

Upgrade

Version history

5.12.0latest on PyPI · released Oct 17, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

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

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

docshttps://moderngl.readthedocs.io/ ↗