DM-Control

1.0.39 · active · verified Thu Apr 16

DM-Control is a Python library from Google DeepMind that provides continuous control environments and Python bindings for the MuJoCo physics engine. It's widely used in reinforcement learning research for creating and interacting with physically realistic simulated agents. The library is actively maintained with frequent releases, often tied to updates in the underlying MuJoCo engine.

Common errors

```
GLFWError: Failed to initialize GLFW
```
cause The GLFW graphics library is not correctly installed or configured on your system, preventing the `dm_control.viewer` from initializing.

fix Install 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'
```
cause The `dm-control` package is not installed or not available in your Python environment.

fix Ensure `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
```
cause 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.

fix Ensure 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.

Warnings

gotcha Rendering with `dm_control.viewer` typically requires a system-level GLFW installation, not just `pip install glfw`. Without it, you will encounter `GLFWError`.
Fix: Install 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]`.
breaking DM-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`.
Fix: Pin `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.
gotcha The `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.
Fix: Understand 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.

Install

pip install dm-control Stable Release
sudo apt-get install libglfw3 # Or equivalent for your OS, e.g., brew install glfw for macOS pip install dm-control[viewer] With Viewer Support (requires system GLFW)

Imports

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
wrong:
```
from dm_control import Physics
```
correct:
```
from dm_control.mujoco 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.

Quickstart

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)

view raw JSON →