Environment:Google deepmind Dm control GLFW Desktop Rendering

Knowledge Sources	dm_control GLFW
Domains	Infrastructure, Rendering
Last Updated	2026-02-15 05:00 GMT

Overview

GLFW-backed OpenGL rendering context for GPU-accelerated windowed rendering on desktop systems with a display server.

Description

This environment provides the GLFW rendering backend for dm_control. GLFW is the highest priority backend in dm_control's auto-detection order (GLFW > EGL > OSMesa). It requires a display server (X11/Wayland on Linux, native on macOS/Windows) and provides hardware-accelerated rendering. It is the only backend that supports the interactive `dm_control.viewer` GUI. On macOS, all GLFW operations must execute on the main thread.

Usage

Use this environment for interactive visualization using `dm_control.viewer.launch()` or any workflow that requires windowed rendering on a desktop machine. It is automatically selected when available, or can be forced via `MUJOCO_GL=glfw`.

System Requirements

Category	Requirement	Notes
OS	Linux with X11/Wayland, macOS, or Windows	Requires a display server
Hardware	GPU with OpenGL support	Integrated or discrete GPU
Display	Active display or virtual framebuffer (Xvfb)	Required for GLFW window creation
Libraries	GLFW3, GLEW	`libglfw3` and `libglew2.0` on Linux

Dependencies

System Packages

`libglfw3` (Linux: `sudo apt-get install libglfw3`)
`libglew2.0` (Linux: `sudo apt-get install libglew2.0`)

Python Packages

`glfw` (Python GLFW bindings)

Credentials

No credentials required.

Quick Install

# Linux (Ubuntu/Debian)
sudo apt-get install libglfw3 libglew2.0

# macOS (Homebrew)
brew install glfw
export DYLD_LIBRARY_PATH=$(brew --prefix)/lib:$DYLD_LIBRARY_PATH

# Python package
pip install glfw

# Force GLFW backend
export MUJOCO_GL=glfw

Code Evidence

Backend auto-detection priority from `_render/__init__.py:61-66`:

_ALL_RENDERERS = (
    (constants.GLFW, _import_glfw),
    (constants.EGL, _import_egl),
    (constants.OSMESA, _import_osmesa),
)

GLFW import guard with error standardization from `_render/glfw_renderer.py:23-30`:

try:
    import glfw
except (ImportError, IOError, OSError) as exc:
    raise ImportError('{}: {}'.format(type(exc).__name__, exc)) from exc
try:
    glfw.init()
except glfw.GLFWError as exc:
    raise ImportError('{}: {}'.format(type(exc).__name__, exc)) from exc

MUJOCO_GL environment variable check from `_render/__init__.py:31`:

BACKEND = os.environ.get(constants.MUJOCO_GL)

GLFW backend synonyms from `_render/constants.py:29`:

GLFW = ('glfw', 'on', 'enable', 'enabled', 'true', '1', '')

GPU detection flag from `_render/__init__.py:109`:

USING_GPU = BACKEND in constants.EGL + constants.GLFW

Common Errors

Error Message	Cause	Solution
`ImportError: GLFWError: Failed to initialize GLFW`	No display server available	Use EGL (`MUJOCO_GL=egl`) or OSMesa (`MUJOCO_GL=osmesa`) for headless rendering
`ImportError: glfw`	GLFW Python package not installed	`pip install glfw` and install system `libglfw3`
Viewer window freezes on macOS	GLFW called from non-main thread	Ensure viewer code runs on the main thread

Compatibility Notes

macOS: GLFW operations must run on the main thread. Rendering tests use single-threaded mode on Darwin.
Headless servers: GLFW will not work on headless machines without X11/Xvfb. Use EGL or OSMesa instead.
Virtual framebuffer: On CI systems, use `xvfb-run` to provide a virtual display for GLFW.
High DPI (macOS): Retina display detection is implemented via `system_profiler SPDisplaysDataType`.
High DPI (Linux): Not yet implemented (TODO in `viewer/renderer.py:65`).

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment