dm-control

dm-control

Use this repo skill when a task involves Google's dm_control package: DeepMind Control Suite environments, MuJoCo simulation through dm_control.mujoco, PyMJCF model construction, Composer custom tasks, locomotion/manipulation task families, pixel observations, viewer launchers, or rendering backend troubleshooting.

First checks

• Install public releases with pip install dm_control; install unreleased source with pip install git+https://github.com/google-deepmind/dm_control.git.
• Do not use editable installs for normal use. dm_control generates legacy MuJoCo bindings during installation, and editable installs can leave dm_control.mujoco.wrapper.mjbindings partially initialized.
• Run scripts/check_dm_control_install.py for an installed-package smoke check that imports core modules, loads one Control Suite task, builds a tiny PyMJCF model, and optionally probes rendering.
• Run scripts/list_dm_control_tasks.py to list installed Control Suite and manipulation task registries before choosing names.
• Read references/installation-and-backends.md when a task needs installation, MuJoCo/OpenGL backend selection, optional rendering, or Blender exporter constraints.
• Read references/package-overview.md for the component map, API entry points, and how the sub-skills fit together.
• Read references/troubleshooting.md for cross-cutting install/import, task selection, backend, and package-data failures.

Route by task

User task	Read next
Load a Control Suite benchmark, step an environment, inspect action/observation specs, use wrappers, or create a random rollout	suite-rl-workflows
Build, parse, compose, export, compile, step, or inspect a MuJoCo/MJCF model with PyMJCF or dm_control.mujoco.Physics	mjcf-mujoco-models
Create a custom Composer Entity, Task, observable, variation, arena, robot, or composer.Environment	composer-environments
Use high-level locomotion, soccer, walker, mocap, prop, or manipulation task families	locomotion-manipulation
Render frames, use pixel observations, launch the viewer, choose MUJOCO_GL, diagnose headless OpenGL, or reason about the Blender exporter	rendering-viewer-assets

Operating defaults

1. Prefer installed-package imports over source-tree assumptions. The public distribution name and import package are both dm_control.
2. Start from CPU/non-rendering simulation unless the user explicitly needs images, camera observations, a viewer, EGL, OSMesa, GLFW, or Blender export.
3. Validate task names from registries before loading them: suite.TASKS_BY_DOMAIN, suite.ALL_TASKS, manipulation.ALL, and manipulation.TAGS.
4. For RL loops, use dm_env.TimeStep semantics: reset first, sample actions within action_spec(), step until time_step.last(), and inspect reward, discount, and observation keys.
5. For custom environments, decide whether the request is a ready-made task selection problem (suite / manipulation / locomotion) or a model/task-construction problem (mjcf / Composer).
6. Keep rendering failures separate from simulation failures. A Control Suite task can reset/step correctly even when GLFW warns that DISPLAY is missing; only pixel/render/viewer tasks require backend fixes.
7. When using cameras or pixel wrappers on headless Linux, try MUJOCO_GL=egl first when a compatible NVIDIA/EGL stack is available; use OSMesa only when system OSMesa libraries are installed; use GLFW only with a display.
8. Treat dm_control.blender.mujoco_exporter as optional and system-mutating: it requires Blender, and add-on installation should be an explicit user choice.

Minimal smoke snippets

from dm_control import suite
import numpy as np

env = suite.load('cartpole', 'balance')
time_step = env.reset()
action_spec = env.action_spec()
action = np.zeros(action_spec.shape, dtype=action_spec.dtype)
time_step = env.step(action)
print(time_step.reward, time_step.discount, time_step.observation.keys())

from dm_control import mjcf

model = mjcf.RootElement(model='smoke')
model.worldbody.add('geom', name='floor', type='plane', size=[1, 1, 0.1])
physics = mjcf.Physics.from_mjcf_model(model)
physics.step()
print(physics.model.nbody, physics.data.time)

Verification notes

• Safe native verification should prefer small CPU cases first: Control Suite registry/loading, PyMJCF model compilation, MuJoCo named access/math, Composer environment reset/step, and manipulation registry tasks.
• Rendering native checks are backend-specific. Use the bundled render probe before asserting pixel observations or viewer behavior.
• Long locomotion, mocap, soccer, GUI, Blender, benchmark-scale, or data-download workflows should be treated as optional or documentation-backed unless the user provides runtime budget and dependencies.