Environment:Farama Foundation Gymnasium MuJoCo Physics Backend

Knowledge Sources	Gymnasium MuJoCo
Domains	Reinforcement_Learning, Physics_Simulation
Last Updated	2026-02-15 03:00 GMT

Overview

MuJoCo physics engine environment with OpenGL rendering backends (glfw, egl, osmesa) for continuous control robotics tasks.

Description

This environment provides the MuJoCo physics simulation backend required for all MuJoCo-based Gymnasium environments (Ant, HalfCheetah, Hopper, Humanoid, Walker2d, Swimmer, Reacher, Pusher, InvertedPendulum, InvertedDoublePendulum, HumanoidStandup). It includes the MuJoCo library, imageio for frame capture, and packaging for version detection. The rendering system supports three OpenGL backends selectable via the `MUJOCO_GL` environment variable: `glfw` (default, requires display), `egl` (headless GPU rendering), and `osmesa` (software rendering).

Usage

Use this environment when running any MuJoCo-based Gymnasium environment. It is required by all v4 and v5 MuJoCo environments. The `MUJOCO_GL` environment variable must be set appropriately for headless servers (use `egl` for GPU-accelerated headless or `osmesa` for CPU-only headless).

System Requirements

Category	Requirement	Notes
OS	Linux (recommended), macOS	Windows support limited
Hardware	GPU recommended	Required for `egl` backend; `osmesa` works CPU-only
Display	X11 or Wayland	Required for `glfw` backend; not needed for `egl`/`osmesa`
Disk	~200MB	MuJoCo library + assets

Dependencies

System Packages

OpenGL libraries (libGL, libEGL, or libOSMesa depending on backend)
`glfw` (Python binding, imported directly by mujoco_rendering.py)

Python Packages

`mujoco` >= 2.1.5
`imageio` >= 2.14.1
`packaging` >= 23.0

Credentials

`MUJOCO_GL` (optional): OpenGL backend selector. Must be one of `glfw`, `egl`, or `osmesa`. Defaults to auto-detection if not set.

Quick Install

# Install Gymnasium with MuJoCo extras
pip install "gymnasium[mujoco]"

# For headless servers (no display)
export MUJOCO_GL=egl   # GPU-accelerated headless
# or
export MUJOCO_GL=osmesa # CPU-only software rendering

Code Evidence

MuJoCo import guard from `gymnasium/envs/mujoco/mujoco_env.py:10-15`:

try:
    import mujoco
except ImportError as e:
    raise error.DependencyNotInstalled(
        'MuJoCo is not installed, run `pip install "gymnasium[mujoco]"`'
    ) from e

MuJoCo version detection from `gymnasium/envs/mujoco/mujoco_rendering.py:12-14`:

# The marker API changed in MuJoCo 3.2.0, so we check the mujoco version and set a flag that
# determines which function we use when adding markers to the scene.
_MUJOCO_MARKER_LEGACY_MODE = Version(mujoco.__version__) < Version("3.2.0")

OpenGL backend selection from `gymnasium/envs/mujoco/mujoco_rendering.py:35-39,202-209`:

_ALL_RENDERERS = {
    "glfw": _import_glfw,
    "egl": _import_egl,
    "osmesa": _import_osmesa,
}

# In OffScreenViewer.__init__:
self.backend = os.environ.get("MUJOCO_GL")
if self.backend is not None:
    try:
        self.opengl_context = _ALL_RENDERERS[self.backend](width, height)
    except KeyError as e:
        raise RuntimeError(
            f"Environment variable {'MUJOCO_GL'} must be one of {_ALL_RENDERERS.keys()!r}: got {self.backend!r}."
        ) from e

Common Errors

Error Message	Cause	Solution
`DependencyNotInstalled: MuJoCo is not installed`	mujoco package missing	`pip install "gymnasium[mujoco]"`
`MUJOCO_GL must be one of {'glfw', 'egl', 'osmesa'}`	Invalid MUJOCO_GL value	Set to `glfw`, `egl`, or `osmesa`
`GLFWError: Failed to initialize`	No display available for glfw	Use `export MUJOCO_GL=egl` or `export MUJOCO_GL=osmesa`
`mujoco v2 and v3 based environments have been moved`	Using deprecated env versions	Use v4 or v5 environments, or install gymnasium-robotics

Compatibility Notes

MuJoCo 3.2.0+: The marker API changed; Gymnasium auto-detects and uses the appropriate API via `_MUJOCO_MARKER_LEGACY_MODE`.
Headless servers: Must set `MUJOCO_GL=egl` (requires GPU) or `MUJOCO_GL=osmesa` (CPU fallback).
Deprecated MuJoCo v2/v3 envs: Moved to `gymnasium-robotics` package. Attempting to use them raises `ImportError` with migration instructions.
render_fps assertion: MuJoCo environments assert that `render_fps` metadata matches `1.0 / dt` from the physics timestep.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment