Environment:ARISE Initiative Robosuite GPU Rendering

Knowledge Sources	robosuite MuJoCo Rendering
Domains	Infrastructure, Robotics_Simulation, GPU_Computing
Last Updated	2026-02-15 07:00 GMT

Overview

GPU-accelerated offscreen rendering environment using EGL on Linux, CGL on macOS, or WGL on Windows for headless MuJoCo simulation image generation.

Description

This environment configures GPU-accelerated rendering for robosuite's offscreen image generation pipeline. On Linux, it uses EGL (via PyOpenGL and MuJoCo's EGL extension) to create headless GPU rendering contexts without requiring a display server. The rendering backend is controlled by the `MUJOCO_GL` environment variable and the `MUJOCO_GPU_RENDERING` macro flag. The system supports multi-GPU selection via `CUDA_VISIBLE_DEVICES` and `MUJOCO_EGL_DEVICE_ID`. A global rendering lock ensures thread safety across concurrent render calls.

Usage

Use this environment when running offscreen rendering for camera observations, video recording, or any workflow that requires `has_offscreen_renderer=True`. This is mandatory for RL training with image observations, demonstration recording with visual data, and any headless server deployment.

System Requirements

Category	Requirement	Notes
OS	Linux (primary), macOS, Windows	EGL rendering is Linux-only; macOS uses CGL; Windows uses WGL
Hardware	NVIDIA GPU with EGL support	Required for Linux headless rendering
Drivers	NVIDIA driver with EGL PLATFORM_DEVICE extension	Required for `eglQueryDevicesEXT`
Display	None required (headless)	EGL enables rendering without X11/Wayland

Dependencies

System Packages

NVIDIA GPU drivers with EGL support (Linux)
`libEGL` / EGL development libraries

Python Packages

`mujoco` >= 3.3.0 (includes `mujoco.egl` module)
`PyOpenGL` (imported as `OpenGL`)
`opencv-python` (for OpenCV-based viewer fallback)

Credentials

The following environment variables control GPU rendering behavior:

`MUJOCO_GL`: Rendering backend (`egl` for headless GPU, `osmesa` for software, `glx` for X11 GPU)
`CUDA_VISIBLE_DEVICES`: Comma-separated GPU device IDs to make visible
`MUJOCO_EGL_DEVICE_ID`: Specific EGL device index (must be within CUDA_VISIBLE_DEVICES)
`PYOPENGL_PLATFORM`: Auto-set to `egl` by robosuite; must be `egl` or unset

Quick Install

# Core robosuite already includes mujoco with EGL support
pip install robosuite

# For software rendering fallback (no GPU)
export MUJOCO_GL=osmesa
pip install PyOpenGL PyOpenGL-accelerate

# Verify EGL is available
python -c "from mujoco.egl import egl_ext as EGL; print('EGL devices:', len(EGL.eglQueryDevicesEXT()))"

Code Evidence

GPU rendering macro and backend selection from `robosuite/utils/binding_utils.py:37-46`:

if macros.MUJOCO_GPU_RENDERING and os.environ.get("MUJOCO_GL", None) not in ["osmesa", "glx"]:
    if _SYSTEM == "Darwin":
        os.environ["MUJOCO_GL"] = "cgl"
    elif _SYSTEM == "Windows":
        os.environ["MUJOCO_GL"] = "wgl"
    else:
        os.environ["MUJOCO_GL"] = "egl"

CUDA_VISIBLE_DEVICES and EGL device validation from `robosuite/utils/binding_utils.py:29-35`:

CUDA_VISIBLE_DEVICES = os.environ.get("CUDA_VISIBLE_DEVICES", "")
if CUDA_VISIBLE_DEVICES != "":
    MUJOCO_EGL_DEVICE_ID = os.environ.get("MUJOCO_EGL_DEVICE_ID", None)
    if MUJOCO_EGL_DEVICE_ID is not None:
        assert MUJOCO_EGL_DEVICE_ID.isdigit() and (
            MUJOCO_EGL_DEVICE_ID in CUDA_VISIBLE_DEVICES
        ), "MUJOCO_EGL_DEVICE_ID needs to be set to one of the device id specified in CUDA_VISIBLE_DEVICES"

EGL context initialization from `robosuite/renderers/context/egl_context.py:119-127`:

EGL_DISPLAY = create_initialized_egl_device_display(device_id=device_id)
if EGL_DISPLAY == EGL.EGL_NO_DISPLAY:
    raise ImportError(
        "Cannot initialize a EGL device display. This likely means that your EGL "
        "driver does not support the PLATFORM_DEVICE extension, which is "
        "required for creating a headless rendering context."
    )

Global rendering lock from `robosuite/utils/binding_utils.py:9-15`:

# DIRTY HACK copied from mujoco-py - a global lock on rendering
from threading import Lock
_MjSim_render_lock = Lock()

Rendering backend validation from `robosuite/utils/binding_utils.py:60-69`:

_VALID_MUJOCO_GL = ("enable", "enabled", "on", "true", "1", "glfw", "")
if _SYSTEM == "Linux":
    _VALID_MUJOCO_GL += ("glx", "egl", "osmesa")
elif _SYSTEM == "Windows":
    _VALID_MUJOCO_GL += ("wgl",)
elif _SYSTEM == "Darwin":
    _VALID_MUJOCO_GL += ("cgl",)
if _MUJOCO_GL not in _VALID_MUJOCO_GL:
    raise RuntimeError(f"invalid value for environment variable MUJOCO_GL: {_MUJOCO_GL}")

Common Errors

Error Message	Cause	Solution
`Cannot initialize a EGL device display`	EGL driver does not support PLATFORM_DEVICE extension	Install NVIDIA drivers with EGL support; verify with `eglQueryDevicesEXT()`
`invalid value for environment variable MUJOCO_GL`	Unsupported rendering backend for current OS	Use valid values: `egl`/`osmesa`/`glx` on Linux, `cgl` on macOS, `wgl` on Windows
`MUJOCO_EGL_DEVICE_ID needs to be set to one of the device id specified in CUDA_VISIBLE_DEVICES`	EGL device ID not in visible CUDA devices	Ensure `MUJOCO_EGL_DEVICE_ID` matches a value in `CUDA_VISIBLE_DEVICES`
`Cannot use EGL rendering platform. The PYOPENGL_PLATFORM environment variable is set to {X}`	PYOPENGL_PLATFORM conflicts with EGL	Unset `PYOPENGL_PLATFORM` or set it to `egl`
`EGL failed to find a framebuffer configuration`	EGL attributes incompatible with GPU	Check GPU driver version and EGL capabilities
`Failed to make the EGL context current`	Stale or corrupted EGL context	Restart process; check for multi-threading issues

Compatibility Notes

Linux (EGL): Primary headless rendering path. Requires NVIDIA drivers with EGL PLATFORM_DEVICE extension. Used automatically when `MUJOCO_GPU_RENDERING=True`.
Linux (OSMesa): Software fallback for systems without GPU. Set `MUJOCO_GL=osmesa`. Significantly slower but requires no GPU.
Linux (GLX): X11-based GPU rendering. Requires a running X server or virtual framebuffer (Xvfb).
macOS (CGL): Native GPU rendering. Set automatically. No EGL support.
Windows (WGL): Native GPU rendering. Set automatically. Requires mujoco.dll loading.
Multi-GPU: Use `CUDA_VISIBLE_DEVICES` to select GPUs and `MUJOCO_EGL_DEVICE_ID` to pick a specific device. When multiple comma-separated values are in `CUDA_VISIBLE_DEVICES`, use `render_gpu_device_id` parameter in environment constructor.
Thread Safety: All rendering calls are serialized via a global lock (`_MjSim_render_lock`). Multi-threaded rendering is supported but not parallel.
Scene Limits: `maxgeom` is set to 10000 in MjvScene to support large-scale scenes.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment