Install & Compatibility
Where this runs
tested against v0.1.45 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 308.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 15.0s · import 0.000s · 299MB
311MB installed
● package 311MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pyrender
✓ import pyrender
Primary import for all Pyrender functionalities.
Mesh
✓ import pyrender
mesh = pyrender.Mesh(...)
Access classes and functions as attributes of the main 'pyrender' module.
Scene
✓ import pyrender
scene = pyrender.Scene(...)
Access classes and functions as attributes of the main 'pyrender' module.
Viewer
✓ import pyrender
viewer = pyrender.Viewer(...)
Access classes and functions as attributes of the main 'pyrender' module.
This quickstart demonstrates how to load a basic mesh using `trimesh`, add it to a Pyrender scene, set up a camera and lighting, and then display the scene in an interactive viewer. For offscreen rendering, a `pyrender.OffscreenRenderer` would be used instead of `pyrender.Viewer`.
import trimesh
import pyrender
# Load a mesh (e.g., a simple box)
fuze_trimesh = trimesh.creation.icosphere()
mesh = pyrender.Mesh.from_trimesh(fuze_trimesh)
# Create a scene
scene = pyrender.Scene()
scene.add(mesh)
# Add a camera
camera = pyrender.PerspectiveCamera(yfov=0.8, aspectRatio=1.0)
camera_pose = [1.0, 0.0, 0.0, 0.0,
0.0, 1.0, 0.0, 0.0,
0.0, 0.0, 1.0, 3.0,
0.0, 0.0, 0.0, 1.0]
scene.add(camera, pose=camera_pose)
# Add some lighting
light = pyrender.DirectionalLight(color=[1.0, 1.0, 1.0], intensity=3.0)
light_pose = [0.0, 0.0, 0.0, 0.0,
-0.5, 0.8, 0.0, 0.0,
0.0, 0.0, 1.0, 0.0,
0.0, 0.0, 0.0, 1.0]
scene.add(light, pose=light_pose)
# View the scene
pyrender.Viewer(scene, use_raymond_lighting=True)
Debug
Known issues
breakingPyrender versions on PyPI (including 0.1.45) may be broken on Python 3.12 and 3.13 due to an OpenGL compatibility issue (specifically with OpenGL 3.1.0). A fix exists in the GitHub repository but has not yet been released to PyPI as of late 2025.fixConsider installing directly from the GitHub repository (`pip install git+https://github.com/mmatl/pyrender.git`) to get the latest fixes, or use an older Python version (e.g., 3.11 or lower).
affects: 0.1.45 (and possibly earlier) on Python >= 3.12
gotchaOffscreen rendering on headless servers often requires specific setup for OpenGL contexts. You might need to install/rebuild Mesa with OSMesa support or ensure EGL 1.5 is available for GPU acceleration.fixRefer to the official Pyrender documentation's 'Installation Guide' and 'Offscreen Rendering' sections for detailed instructions on configuring OSMesa or EGL for your environment.
affects: All versions
gotchaMacOS users may encounter issues with OpenGL contexts when using `pyrender` due to an unreleased `pyglet` fix. A specific fork of `pyglet` is required.fixManually install the compatible `pyglet` fork: `git clone https://github.com/mmatl/pyglet.git && cd pyglet && pip install .` before installing `pyrender`.
affects: All versions on MacOS
gotchaThe latest PyPI release (0.1.45) is from February 2021. Important bug fixes and improvements that have landed in the GitHub repository since then are not available via `pip install pyrender`.fixFor the most up-to-date and potentially more stable version (especially for newer Python environments), install Pyrender directly from its GitHub repository: `pip install git+https://github.com/mmatl/pyrender.git`.
affects: <=0.1.45
Errors
Common errors & fixes
pyglet.gl.lib.GLException: Cannot create GL context
Pyrender, through its dependency Pyglet, fails to create an OpenGL rendering context when a display server or proper graphics drivers are not available, commonly in headless environments (e.g., servers, Docker containers).
fixFor headless rendering, use a virtual display server like `xvfb` (e.g., `xvfb-run -a python your_script.py`) or configure Pyrender to use an EGL or OSMesa backend, ensuring necessary `mesa` libraries (like `libegl1-mesa-dev` or `libosmesa6-dev`) are installed on your system.
Segmentation fault (core dumped)
This severe error often indicates a low-level crash due to issues with OpenGL drivers, memory management, or incompatibility between pyrender and its graphics dependencies (pyglet, moderngl) on specific hardware or operating system configurations, especially when running headless or with outdated drivers.
fixEnsure your graphics drivers are up-to-date. If running headless, verify that `xvfb` or EGL/OSMesa backends are correctly set up and that compatible `mesa` libraries are installed. Consider upgrading or downgrading `pyrender` and its core dependencies (`pyglet`, `moderngl`, `trimesh`) to known stable versions.
ImportError: cannot import name 'load_image' from 'trimesh.util'
This error arises when the installed `trimesh` library, a key dependency of `pyrender`, has an API change where `load_image` was moved, renamed, or removed from `trimesh.util`, causing a version incompatibility.
fixUpgrade your `trimesh` installation to a version compatible with your `pyrender` version (e.g., `pip install --upgrade trimesh`). If upgrading causes other issues, try installing a specific `trimesh` version known to work with your `pyrender` version, typically found in `pyrender`'s `requirements.txt` on its GitHub repository.
AttributeError: 'Context' object has no attribute 'create_shader_program'
This `AttributeError` typically occurs due to an incompatibility between your `pyrender` version and the `moderngl` library, which `pyrender` uses for its OpenGL context, implying that the `create_shader_program` method's availability or signature has changed in `moderngl`.
fixEnsure `pyrender` and `moderngl` are compatible by upgrading both libraries (e.g., `pip install --upgrade pyrender moderngl`). If the issue persists, check `pyrender`'s official documentation or GitHub `requirements.txt` for the specific `moderngl` version it was developed against and install that version (e.g., `pip install moderngl==X.Y.Z`).
Upgrade
Version history
0.1.45latest on PyPI · released Feb 18, 2021
Audit
Dependencies
trimeshrequiredRecommended for loading and manipulating various 3D mesh types (OBJ, STL, DAE, PLY, etc.) due to deep integration with Pyrender's mesh objects.