Heuristic:Google deepmind Dm control Rendering Backend Selection Tips
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Rendering, Optimization |
| Last Updated | 2026-02-15 05:00 GMT |
Overview
Decision framework for selecting the appropriate OpenGL rendering backend (GLFW, EGL, or OSMesa) based on hardware availability and use case.
Description
dm_control supports three OpenGL rendering backends with different tradeoffs. The auto-detection priority is GLFW > EGL > OSMesa, but the optimal choice depends on the deployment context. Selecting the wrong backend causes either import failures (headless server + GLFW) or unnecessary performance penalties (GPU server + OSMesa). The `MUJOCO_GL` environment variable overrides auto-detection.
Usage
Apply this heuristic when setting up a dm_control environment for the first time, when migrating between desktop and server, or when debugging rendering failures. The decision tree is: Desktop with display? Use GLFW. Headless server with GPU? Use EGL. No GPU at all? Use OSMesa.
The Insight (Rule of Thumb)
- Action: Set `MUJOCO_GL` environment variable to the appropriate backend before importing dm_control.
- Decision Tree:
- Desktop with display server (development, interactive use): `MUJOCO_GL=glfw` (or leave unset for auto-detection). Only GLFW supports the interactive `dm_control.viewer`.
- Headless server with NVIDIA GPU (cloud training, CI with GPU): `MUJOCO_GL=egl`. Use `MUJOCO_EGL_DEVICE_ID=N` to pin to specific GPU on multi-GPU systems.
- CPU-only / no GPU (Docker, CI without GPU): `MUJOCO_GL=osmesa`. Slowest but works everywhere.
- No rendering needed (pure RL with state observations): `MUJOCO_GL=off` to disable rendering entirely and avoid import errors.
- Trade-off: GLFW requires a display; EGL requires NVIDIA drivers with EGL extensions; OSMesa is universally compatible but CPU-only and slower.
- PYOPENGL_PLATFORM: Do NOT manually set this variable. dm_control automatically sets it to match the selected backend. Conflicting values cause `ImportError`.
Reasoning
The auto-detection (GLFW > EGL > OSMesa) works well for desktop development but fails predictably on headless servers where GLFW import fails, then EGL may fail if NVIDIA EGL extensions are missing, leaving only OSMesa. Explicitly setting `MUJOCO_GL` avoids the overhead of failed imports and ensures the intended backend is used. The `MUJOCO_GL=off` option is valuable for state-only RL pipelines that never call `render()`, avoiding unnecessary OpenGL library dependencies entirely.
Code evidence from `_render/__init__.py:16-23`:
"""OpenGL context management for rendering MuJoCo scenes.
By default, the `Renderer` class will try to load one of the following rendering
APIs, in descending order of priority: GLFW > EGL > OSMesa.
It is also possible to select a specific backend by setting the `MUJOCO_GL=`
environment variable to 'glfw', 'egl', or 'osmesa'.
"""
Backend synonym values from `_render/constants.py:28-32`:
OSMESA = ('osmesa',)
GLFW = ('glfw', 'on', 'enable', 'enabled', 'true', '1', '')
EGL = ('egl',)
NO_RENDERER = ('off', 'disable', 'disabled', 'false', '0')