Environment:Google deepmind Dm control OSMesa Software Rendering
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Rendering |
| Last Updated | 2026-02-15 05:00 GMT |
Overview
OSMesa-backed software rendering context for CPU-only environments without GPU hardware or drivers.
Description
This environment provides the OSMesa (Off-Screen Mesa) rendering backend for dm_control. OSMesa is a purely software-based OpenGL implementation that requires no GPU hardware, no display server, and no GPU drivers. It is the lowest priority in dm_control's auto-detection order (GLFW > EGL > OSMesa) and serves as the fallback when neither GLFW nor EGL is available. Rendering performance is significantly slower than GPU-accelerated backends but works universally on any system with the Mesa libraries installed.
Usage
Use this environment when no GPU is available or when running on minimal systems (Docker containers, CI runners, CPU-only cloud instances). Activate by setting `MUJOCO_GL=osmesa`.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (primary), macOS, Windows | Works on any platform with Mesa libraries |
| Hardware | CPU only | No GPU required |
| Libraries | Mesa OSMesa, GLX | `libosmesa6` and `libgl1-mesa-glx` on Linux |
Dependencies
System Packages
- `libosmesa6` (Linux: `sudo apt-get install libosmesa6`)
- `libgl1-mesa-glx` (Linux: `sudo apt-get install libgl1-mesa-glx`)
Python Packages
- `pyopengl` >= 3.1.4
Credentials
The following environment variables control OSMesa behavior:
- `MUJOCO_GL`: Set to `osmesa` to select OSMesa backend.
- `PYOPENGL_PLATFORM`: Automatically set to `osmesa` by dm_control. Do NOT set to a conflicting value.
Quick Install
# Linux (Ubuntu/Debian)
sudo apt-get install libosmesa6 libgl1-mesa-glx
# Force OSMesa backend
export MUJOCO_GL=osmesa
Code Evidence
PYOPENGL_PLATFORM auto-configuration from `_render/pyopengl/osmesa_renderer.py:23-32`:
PYOPENGL_PLATFORM = os.environ.get(constants.PYOPENGL_PLATFORM)
if not PYOPENGL_PLATFORM:
os.environ[constants.PYOPENGL_PLATFORM] = constants.OSMESA[0]
elif PYOPENGL_PLATFORM != constants.OSMESA[0]:
raise ImportError(
'Cannot use OSMesa rendering platform. '
'The PYOPENGL_PLATFORM environment variable is set to {!r} '
'(should be either unset or {!r}).'
.format(PYOPENGL_PLATFORM, constants.OSMESA[0]))
Auto-detection fallback from `_render/__init__.py:96-107`:
for names, import_func in _ALL_RENDERERS:
try:
Renderer = import_func()
BACKEND = names[0]
logging.info('Successfully imported OpenGL backend: %s', names[0])
break
except ImportError:
logging.info('Failed to import OpenGL backend: %s', names[0])
if BACKEND is None:
logging.info('No OpenGL backend could be imported.')
Renderer = _no_renderer()
GPU flag indicates CPU-only rendering from `_render/__init__.py:109`:
USING_GPU = BACKEND in constants.EGL + constants.GLFW
# OSMesa is NOT in this list, so USING_GPU == False for OSMesa
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: Cannot use OSMesa rendering platform. The PYOPENGL_PLATFORM environment variable is set to 'egl'` | Conflicting PYOPENGL_PLATFORM | Unset `PYOPENGL_PLATFORM` or set it to `osmesa` |
| `ImportError: OSMesa` (during auto-detection) | OSMesa libraries not installed | `sudo apt-get install libosmesa6 libgl1-mesa-glx` |
| Slow rendering performance | Software rendering is CPU-bound | Expected behavior; use EGL or GLFW for GPU-accelerated rendering |
Compatibility Notes
- Performance: Software rendering is significantly slower than GPU backends. Only use OSMesa when no GPU is available.
- Interactive viewer: The `dm_control.viewer` GUI requires GLFW and will not work with OSMesa.
- Docker containers: OSMesa is the typical choice for Docker environments without GPU passthrough.
- CI/CD pipelines: Ideal for test environments that need rendering but lack GPU hardware.