Environment:Google deepmind Dm control EGL Headless Rendering
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Rendering, GPU |
| Last Updated | 2026-02-15 05:00 GMT |
Overview
EGL-backed OpenGL rendering context for GPU-accelerated headless rendering without a display server.
Description
This environment provides the EGL rendering backend for dm_control. EGL enables hardware-accelerated rendering on GPU-equipped machines without a windowing system or display server. It is the second priority in dm_control's auto-detection order (GLFW > EGL > OSMesa) and is the recommended backend for headless server workloads such as RL training on cloud GPUs. It requires NVIDIA GPU drivers with EGL device extension support (`EXT_platform_device`, `EXT_device_query`). Multi-GPU selection is supported via the `MUJOCO_EGL_DEVICE_ID` environment variable.
Usage
Use this environment for headless GPU-accelerated rendering on servers without a display. Typical use cases include RL training pipelines that need pixel observations, batch rendering for dataset generation, and cloud-based training. Activate by setting `MUJOCO_GL=egl`.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux | EGL rendering is Linux-only |
| Hardware | NVIDIA GPU with EGL support | Requires proprietary NVIDIA drivers with EGL extensions |
| Drivers | NVIDIA driver with `libEGL.so` and `libOpenGL.so` | Must support `eglQueryDevicesEXT` and `eglGetPlatformDisplayEXT` |
| Libraries | GLEW | `libglew2.0` on Linux |
Dependencies
System Packages
- `libglew2.0` (Linux: `sudo apt-get install libglew2.0`)
- NVIDIA GPU drivers with EGL device extensions
Python Packages
- `pyopengl` >= 3.1.4
Credentials
The following environment variables control EGL behavior:
- `MUJOCO_GL`: Set to `egl` to select EGL backend.
- `PYOPENGL_PLATFORM`: Automatically set to `egl` by dm_control. Do NOT set to a conflicting value.
- `MUJOCO_EGL_DEVICE_ID`: Optional. Integer (0-indexed) selecting which GPU to use for rendering. If unset, tries all available devices.
Quick Install
# Linux (Ubuntu/Debian)
sudo apt-get install libglew2.0
# Ensure NVIDIA drivers are installed with EGL support
# Verify EGL is available:
python -c "import ctypes; ctypes.CDLL('libEGL.so')"
# Force EGL backend
export MUJOCO_GL=egl
# Select specific GPU (optional, for multi-GPU systems)
export MUJOCO_EGL_DEVICE_ID=0
Code Evidence
PYOPENGL_PLATFORM auto-configuration from `_render/pyopengl/egl_renderer.py:26-35`:
PYOPENGL_PLATFORM = os.environ.get(constants.PYOPENGL_PLATFORM)
if not PYOPENGL_PLATFORM:
os.environ[constants.PYOPENGL_PLATFORM] = constants.EGL[0]
elif PYOPENGL_PLATFORM != constants.EGL[0]:
raise ImportError(
'Cannot use EGL rendering platform. '
'The PYOPENGL_PLATFORM environment variable is set to {!r} '
'(should be either unset or {!r}).'
.format(PYOPENGL_PLATFORM, constants.EGL[0]))
GPU device selection from `_render/pyopengl/egl_renderer.py:46-54`:
selected_device = os.environ.get('MUJOCO_EGL_DEVICE_ID', None)
if selected_device is None:
candidates = all_devices
else:
device_idx = int(selected_device)
if not 0 <= device_idx < len(all_devices):
raise RuntimeError(
f'MUJOCO_EGL_DEVICE_ID must be an integer between 0 and '
f'{len(all_devices) - 1} (inclusive), got {device_idx}.')
candidates = all_devices[device_idx:device_idx + 1]
EGL display initialization failure from `_render/pyopengl/egl_renderer.py:73-75`:
EGL_DISPLAY = create_initialized_headless_egl_display()
if EGL_DISPLAY == EGL.EGL_NO_DISPLAY:
raise ImportError('Cannot initialize a headless EGL display.')
Thread executor limitation from `_render/pyopengl/egl_renderer.py:97-98`:
# EGLContext currently only works with `PassthroughRenderExecutor`.
# TODO(b/110927854) Make this work with the offloading executor.
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: Cannot initialize a headless EGL display.` | No GPU with EGL support detected | Verify NVIDIA drivers are installed: `nvidia-smi`; check `libEGL.so` exists |
| `ImportError: Cannot use EGL rendering platform. The PYOPENGL_PLATFORM environment variable is set to 'osmesa'` | Conflicting PYOPENGL_PLATFORM | Unset `PYOPENGL_PLATFORM` or set it to `egl` |
| `RuntimeError: MUJOCO_EGL_DEVICE_ID must be an integer between 0 and N` | Invalid GPU device index | Set to valid index (check available GPUs with `nvidia-smi`) |
| `ImportError` from `egl_ext.py` | EGL extensions not available in driver | Update NVIDIA drivers; ensure `libOpenGL.so` is accessible |
Compatibility Notes
- Thread offloading: EGLContext currently only works with `PassthroughRenderExecutor` (not the offloading executor). Set `DISABLE_RENDER_THREAD_OFFLOADING` to any value if encountering threading issues.
- AMD GPUs: Not supported by this EGL implementation (relies on NVIDIA-specific `EXT_platform_device`).
- Interactive viewer: The `dm_control.viewer` GUI requires GLFW and will not work with EGL. Use EGL for batch/headless rendering only.
- Multi-GPU: Use `MUJOCO_EGL_DEVICE_ID` to pin rendering to a specific GPU on multi-GPU systems.