mujoco-learn

Learn MuJoCo through runnable Python files — not documentation pages.

Each file introduces one concept, is self-contained, and has TODO markers for you to fill in. Complete them in order.

Setup

python -m venv .venv
source .venv/bin/activate        
pip install -e ".[viz,rl,dev]"

All scripts must be run from the repo root so that models/ paths resolve:

python 01_basics/01_hello_mujoco.py

Curriculum

File	Concept
01_basics/01_hello_mujoco.py	Load a model, step once, read state
01_basics/02_mjcf_xml.py	Build models from XML strings
01_basics/03_model_vs_data.py	MjModel (static) vs MjData (dynamic)
01_basics/04_simulation_loop.py	mj_step vs mj_forward, reset
02_visualization/01_passive_viewer.py	Interactive viewer
02_visualization/02_offscreen_render.py	Headless rendering to arrays / video
03_control/01_actuators.py	data.ctrl, clip behavior, passive dynamics
03_control/02_pd_controller.py	PD controller, gain tuning
03_control/03_trajectory.py	Trajectory tracking, min-jerk profile
04_sensing/01_state_readout.py	qpos, xpos, site_xpos, Cartesian velocity
04_sensing/02_sensors.py	sensordata, building observation vectors
04_sensing/03_contacts.py	Contact detection, mj_contactForce
05_gymnasium/01_wrap_as_env.py	Gymnasium env wrapper
05_gymnasium/02_random_policy.py	Evaluation loop, random vs heuristic baseline

Models

File	Description
models/pendulum.xml	1-DOF pendulum — used in basics, visualization, control
models/cartpole.xml	Cart + pole — classic control benchmark
models/arm2dof.xml	2-DOF planar arm with end-effector site

Run python models/models_guide.py for ASCII diagrams and a live parameter breakdown of every model.

Quick Reference

import mujoco

model = mujoco.MjModel.from_xml_path("models/pendulum.xml")  # static
data  = mujoco.MjData(model)                                  # dynamic

mujoco.mj_step(model, data)       # advance one timestep
mujoco.mj_forward(model, data)    # recompute kinematics without advancing time
mujoco.mj_resetData(model, data)  # reset to t=0

data.qpos        # joint positions
data.qvel        # joint velocities
data.ctrl        # actuator inputs  ← write here to drive the robot
data.sensordata  # flat sensor readings
data.xpos        # body positions in world frame  (nbody, 3)
data.site_xpos   # site positions in world frame  (nsite, 3)

See GUIDE.py for the full cheatsheet.

References

• MuJoCo Documentation — official API reference, XML format, and tutorials
• MuJoCo GitHub — source, changelog, and examples
• MuJoCo Menagerie — collection of real robot models ready to drop in
• Gymnasium Documentation — env interface, wrappers, and built-in environments
• Stable-Baselines3 — RL algorithms that work directly with Gymnasium envs

Credits

Built by assistance from Claude code (Anthropic).