Install & Compatibility
Where this runs
tested against v1.0.41 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 14.95s
py 3.11
✕ build_error
✓ 14s
py 3.12
✕ build_error
✓ 14.25s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
432MB installed
● package 432MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
suite
✓ from dm_control import suite
Provides access to standard control environments like 'cartpole' or 'walker'.
Environment
✓ from dm_control.rl import control
Base class for RL environments, though usually not instantiated directly for standard suite tasks.
Physics
✓ from dm_control.mujoco import Physics
✗ from dm_control import Physics
Physics object for low-level interaction with MuJoCo models. Often confused with the top-level package.
viewer
✓ from dm_control import viewer
Module for visualizing MuJoCo environments.
This quickstart loads the 'cartpole/balance' environment and attempts to launch the interactive viewer. The viewer requires the `dm-control[viewer]` extra and a system-wide GLFW installation (e.g., `libglfw3` on Linux). If GLFW is not set up, the viewer might fail, but the environment can still be interacted with programmatically.
import os
from dm_control import suite
from dm_control import viewer
# Load a standard control environment
env = suite.load(domain_name="cartpole", task_name="balance")
# Create a viewer application
# Note: Requires system-level GLFW installation for the viewer to work
# e.g., `sudo apt-get install libglfw3` on Linux or `brew install glfw` on macOS
if os.environ.get('DM_CONTROL_NO_VIEWER') != 'true':
try:
viewer.launch(env)
except Exception as e:
print(f"Could not launch viewer: {e}")
print("Try running without viewer by setting environment variable DM_CONTROL_NO_VIEWER=true")
print("Or ensure GLFW is installed: `pip install dm-control[viewer]` and system-level `libglfw3`.")
else:
print("Viewer explicitly disabled via DM_CONTROL_NO_VIEWER environment variable.")
# Or, manually step through the environment:
# action_spec = env.action_spec()
# time_step = env.reset()
# while not time_step.last():
# action = 0.0 # Example: apply zero action
# time_step = env.step(action)
Debug
Known issues
gotchaRendering with `dm_control.viewer` typically requires a system-level GLFW installation, not just `pip install glfw`. Without it, you will encounter `GLFWError`.fixInstall GLFW development libraries for your operating system (e.g., `sudo apt-get install libglfw3` on Debian/Ubuntu, `brew install glfw` on macOS) and then `pip install dm-control[viewer]`.
affects: All versions
breakingDM-Control bundles a specific version of the MuJoCo physics engine. Upgrading `dm-control` can introduce a new MuJoCo version, potentially causing subtle behavioral changes or API incompatibilities if you are interacting with MuJoCo models at a low level via `dm_control.mujoco`.fixPin `dm-control` to a specific version for critical projects. If using custom MuJoCo models, thoroughly test after any `dm-control` upgrade. Consult the `dm-control` GitHub releases for bundled MuJoCo versions.
affects: All versions, especially across minor/patch releases with MuJoCo upgrades (e.g., 1.0.38 to 1.0.39 upgraded MuJoCo 3.6.0 to 3.7.0).
gotchaThe `mujoco` PyPI package provides direct Python bindings to MuJoCo, separate from the `dm-control` library. While both use MuJoCo, they serve different purposes: `dm-control` focuses on control environments, while `mujoco` provides raw physics engine access. Using both might lead to confusion regarding which MuJoCo version is active.fixUnderstand the scope: use `dm_control.suite` for high-level tasks, and `dm_control.mujoco` for advanced MuJoCo integration within `dm-control`'s framework. Only use the standalone `mujoco` package if you need direct, low-level MuJoCo API access independent of `dm-control`'s abstractions.
affects: All versions
Errors
Common errors & fixes
GLFWError: Failed to initialize GLFW
The GLFW graphics library is not correctly installed or configured on your system, preventing the `dm_control.viewer` from initializing.
fixInstall the GLFW development libraries for your OS (e.g., `sudo apt-get install libglfw3-dev` on Linux, `brew install glfw` on macOS). Ensure you have also installed `dm-control` with viewer extras: `pip install dm-control[viewer]`.
ModuleNotFoundError: No module named 'dm_control.suite'
The `dm-control` package is not installed or not available in your Python environment.
fixEnsure `dm-control` is installed: `pip install dm-control`. Verify your Python environment is active and `pip` is installing into the correct one.
mujoco.FatalError: Could not find license file at /path/to/.mujoco/mjkey.txt
For older MuJoCo versions (before 2.1), a license file was required. While `dm-control` bundles modern MuJoCo, if you are attempting to use an older local MuJoCo installation or custom build, this error can appear.
fixEnsure you are using the MuJoCo version bundled with `dm-control` which does not require a license. If you're manually managing MuJoCo, upgrade to MuJoCo 2.1 or newer, or place a valid `mjkey.txt` in the specified location for older versions. Most users of `dm-control` will not encounter this directly unless they have custom MuJoCo setups.
Upgrade
Version history
1.0.41latest on PyPI · released May 11, 2026
Audit
Dependencies
mujocorequiredBundled C++ library, core physics engine functionality. Python package 'mujoco' is separate but can be installed alongside for direct MuJoCo API access.
glfwoptionalRequired for rendering with the dm_control.viewer module.
absl-pyrequiredUsed for command-line parsing and logging utilities.
numpyrequiredCore numerical operations for array manipulation.