# dm_control: DeepMind's Physics-Based Simulation Stack for Reinforcement Learning

> dm_control is Google DeepMind's Python library for physics-based reinforcement learning simulation, built on the MuJoCo physics engine. It provides Python bindings to MuJoCo, a set of continuous-control RL environments, and tools for composing custom tasks, and it is for RL researchers who need a well-maintained environment suite or want to build their own physics-based tasks.

**google-deepmind/dm_control** — Google DeepMind's software stack for physics-based simulation and Reinforcement Learning environments, using MuJoCo.

- Repository: https://github.com/google-deepmind/dm_control
- Stars: 4,707 · Forks: 768
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-deepmind-dm-control

## What dm_control Adds to the MuJoCo Python Bindings

MuJoCo's own Python package exposes the physics engine's C API through pybind11 bindings. That gives you a simulation object, a data structure, and functions to step the simulation. It does not provide RL environment abstractions, task definitions, reward functions, or the observation and action spaces that RL algorithms expect.

dm_control fills that gap. It wraps the MuJoCo bindings in higher-level components: a set of continuous-control benchmark environments (dm_control.suite), a tool for composing and modifying MuJoCo MJCF models in Python (dm_control.mjcf), a library for defining reusable task components (dm_control.composer), and additional locomotion tasks including multi-agent soccer. For researchers who want to compare RL algorithms on standard benchmarks or build their own tasks from composable pieces, dm_control provides the infrastructure that the raw MuJoCo package does not.

The repository also ships dm_control.viewer, an interactive environment viewer. This is the one component that requires GLFW and therefore cannot run on headless machines: the README notes explicitly that dm_control.viewer can only be used with GLFW and will not work on headless servers.

## The Core Components and What Each Provides

The library is organized as several independent but related packages:

dm_control.mujoco provides Python bindings to the MuJoCo physics engine. Although dm_control has moved most of its binding work to the pybind11-based bindings from the standalone mujoco package, it still relies on some auto-generated legacy components that are produced from MuJoCo's header files during the build process. This is why editable-mode installs are not supported.

dm_control.suite is a collection of Python RL environments for continuous control. Each environment wraps a MuJoCo model with a task that defines observations, actions, and rewards. The suite provides standard benchmarks used in RL research.

dm_control.mjcf is a Python library for composing and modifying MuJoCo MJCF model files. MJCF is MuJoCo's XML-based format for describing physics models. The mjcf library lets you build and modify models programmatically rather than editing XML files by hand.

dm_control.composer is higher-level than mjcf: it provides a framework for defining rich RL environments from reusable, self-contained components. This is what you use when you want to build a custom task from pieces that can be recombined without rewriting the XML model each time.

dm_control.locomotion contains additional task libraries for locomotion research, including dm_control.locomotion.soccer, which implements multi-agent soccer tasks.

## Installing dm_control and Configuring Rendering

Install from PyPI:

```sh
pip install dm_control
```

Editable installs are not supported. The README states this directly: `pip install -e` will fail with ImportError because the auto-generated mjbindings module cannot be resolved in editable mode. If you accidentally install in editable mode, the fix is to uninstall and reinstall without the `-e` flag.

Rendering requires one of three OpenGL backends. GLFW provides windowed hardware-accelerated rendering but does not work on headless machines. EGL provides headless hardware-accelerated rendering and requires a GPU with EGL_EXT_platform_device support, plus GLEW. OSMesa provides purely software-based rendering.

On Debian and Ubuntu, GLFW and GLEW install via:

```sh
sudo apt-get install libglfw3 libglew2.0
```

For software rendering:

```sh
sudo apt-get install libgl1-mesa-glx libosmesa6
```

By default, dm_control tries GLFW first, then EGL, then OSMesa. The README documents that you can specify a particular backend by setting the `MUJOCO_GL=` environment variable to `glfw`, `egl`, or `osmesa`. To specify which GPU EGL uses for rendering, set the `MUJOCO_EGL_DEVICE_ID=` environment variable to the target GPU ID.

On macOS with Homebrew, the DYLD_LIBRARY_PATH must be updated with the path to the GLFW library before running:

```sh
export DYLD_LIBRARY_PATH=$(brew --prefix)/lib:$DYLD_LIBRARY_PATH
```

## The dm_control.suite Benchmark Environments

dm_control.suite is a set of continuous control tasks built on MuJoCo models. These tasks cover standard locomotion and manipulation domains that the RL research community uses for benchmarking algorithms. Each environment provides observations, actions, and a reward signal that follows the dm_env interface.

The suite is one of the two reasons most RL researchers install dm_control. The other is dm_control.composer for custom task building. If you only need to run standard benchmarks, dm_control.suite is what you are after. If you need to compare your results against published work that used dm_control.suite environments, the environments provide a consistent baseline that is maintained as MuJoCo updates.

Version 1.0.47, released on 2026-09-22, tracks MuJoCo 3.14.0. The release notes for each version specify which MuJoCo version it upgrades to, which matters because physics behavior can change across MuJoCo versions. The requirements.txt pins mujoco==3.14.0 for this release, along with specific versions of numpy, scipy, and other dependencies. The numpy version varies by Python version: numpy==2.3.2 for Python 3.11 and later, numpy==2.2.6 for Python 3.10, and numpy==2.0.2 for Python 3.9.

## The Editable Install Restriction and What It Means in Practice

The README's warning about editable mode is one of the most practically important constraints in dm_control. The auto-generated mjbindings module, which wraps MuJoCo header files in Python, is generated at install time into the `dm_control/mujoco/wrapper/mjbindings/` directory. When pip installs the package normally, this directory is populated with the generated files. When pip installs in editable mode, it does not run the full build, so the mjbindings directory remains empty, and any import of dm_control.mujoco fails with an ImportError.

The error message the README shows is:

```
ImportError: cannot import name 'constants' from partially initialized module 'dm_control.mujoco.wrapper.mjbindings'
```

The solution is always the same: `pip uninstall dm_control` followed by a regular `pip install dm_control`. Developers who want to modify dm_control's source code must do a regular install, make changes, and then reinstall to see the effects. This makes the iteration cycle slower than for packages that support editable mode.

An alternative for users who want the latest unreleased version is to install from the GitHub repository directly:

```sh
pip install git+https://github.com/google-deepmind/dm_control.git
```

This still performs a full build, so it does not have the editable mode problem, but it installs whatever the current commit of the main branch contains rather than a stable release.

## dm_control vs the Raw MuJoCo Python Package

The mujoco Python package (from google-deepmind/mujoco) is the official Python binding to the MuJoCo physics engine. It provides direct access to the MuJoCo C API from Python, including the MjModel and MjData structures, stepping functions, and renderer classes. It does not provide RL environment abstractions, task reward functions, or the composer framework.

dm_control sits on top of the mujoco package. Since version 1.0.0, dm_control has moved most of its binding work to the pybind11-based bindings from the mujoco package, keeping only the auto-generated legacy components as described above. This means dm_control is not an alternative to the mujoco package; it is a layer above it.

The practical question is whether you need the RL environment abstractions and tools that dm_control provides. If you are writing a custom physics simulation in MuJoCo that does not fit the RL paradigm, you may not need dm_control at all. If you are doing RL research and want standard benchmarks or composable task building, dm_control is the appropriate layer to use.

## Maintenance, Versioning, and License

dm_control uses semantic versioning from version 1.0.0 onward. Before 1.0.0, the package used a `0.0.N` scheme where N was an internal revision number. Semantic versioning means that minor version bumps such as 1.0.46 to 1.0.47 may include behavior changes tied to MuJoCo upgrades, and the requirements.txt pins exact MuJoCo versions to avoid surprises.

The repository is licensed under the Apache License 2.0. The Apache 2.0 license permits use, reproduction, distribution, and creation of derivative works, including commercial use, with no copyleft requirement. It requires preservation of the copyright notice and the license file in distributions.

The AUTHORS file lists the contributors, and the CONTRIBUTING.md file documents the process for submitting patches. The tutorial notebook is available on Google Colab, which provides an interactive introduction to the library without requiring a local install. The last push to the repository was on 2026-09-09, and the most recent release was 1.0.47 on 2026-09-22.

## Conclusion

dm_control is the right choice for RL researchers who need a maintained set of continuous-control benchmark environments on MuJoCo, or who need Python-level tools for composing physics-based tasks. Researchers who only need the MuJoCo Python bindings without the RL environment layer can use the standalone mujoco package instead. Before installing, note that editable-mode installs are not supported and will fail with import errors. Version 1.0.47 was released on 2026-09-22, tracking MuJoCo 3.14.0, and the repository follows semantic versioning since 1.0.0.

## FAQ

### What is the difference between dm_control and the mujoco Python package?

The mujoco package provides direct Python bindings to the MuJoCo physics engine without any RL environment abstractions. dm_control builds on top of it to add the suite of RL benchmark environments, the mjcf model composition library, the composer framework for custom tasks, and the interactive viewer.

### Why does installing dm_control in editable mode fail?

dm_control generates Python bindings from MuJoCo header files during the build process. Editable-mode installs skip this build step, leaving the generated mjbindings directory empty and causing ImportError. The fix is to uninstall and reinstall without the -e flag.

### How do I run dm_control on a headless server without a display?

Set the MUJOCO_GL environment variable to egl or osmesa. EGL requires a GPU with EGL_EXT_platform_device support and GLEW. OSMesa is software-based and works without a GPU but is slower. GLFW requires a windowing system and cannot be used on headless machines.

## Sources

- [google-deepmind/dm_control on GitHub](https://github.com/google-deepmind/dm_control)
- [Issues](https://github.com/google-deepmind/dm_control/issues)
- [License: Apache-2.0](https://github.com/google-deepmind/dm_control/blob/main/LICENSE)
- [README](https://github.com/google-deepmind/dm_control/blob/main/README.md)
- [Releases](https://github.com/google-deepmind/dm_control/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-deepmind-dm-control