A modern tutorial for getting started with MuJoCo — a fast, accurate physics engine for robotics, biomechanics, and reinforcement learning.
MuJoCo is open-source (Apache 2.0) and maintained by Google DeepMind. Since v3.0, it includes GPU-accelerated simulation via MJX.
MuJoCo is a pure Python package — no license keys, no system dependencies:
pip install mujoco gymnasium[mujoco] mediapyThat's it. For interactive visualization you also need a display (or use offscreen rendering in notebooks).
conda create -n mujoco-tut python=3.11
conda activate mujoco-tut
pip install -r requirements.txtimport mujoco
import mujoco.viewer
model = mujoco.MjModel.from_xml_string("""
<mujoco>
<worldbody>
<light pos="0 0 3" dir="0 0 -1"/>
<geom type="plane" size="5 5 0.1"/>
<body pos="0 0 2">
<joint type="free"/>
<geom type="sphere" size="0.2" rgba="1 0 0 1"/>
</body>
</worldbody>
</mujoco>
""")
data = mujoco.MjData(model)
# Launch interactive viewer
mujoco.viewer.launch(model, data)For headless/notebook rendering, see examples/offscreen_rendering.py.
Left to right: trajectory tracking, LQR balancing, impedance control, pick-and-place
| Example | Description |
|---|---|
examples/projectile.py |
Projectile with drag force |
examples/pendulum_control.py |
PD control of a pendulum |
examples/double_pendulum.py |
Double pendulum swing-up control |
examples/hopper.py |
2D hopper with open-loop jumping |
examples/inverse_kinematics.py |
Damped least-squares IK with Jacobians |
examples/contact_forces.py |
Reading contact info & forces |
examples/domain_randomization.py |
Varying physics params across episodes |
examples/menagerie_robot.py |
Loading robots from MuJoCo Menagerie |
examples/mjx_parallel.py |
GPU-parallel sim with MJX (JAX) |
examples/gymnasium_env.py |
Using Gymnasium's MuJoCo envs |
examples/offscreen_rendering.py |
Headless rendering & video export |
examples/trajectory_tracking.py |
Arm follows circular path (task-space PD) |
examples/operational_space_control.py |
Full dynamics compensation in task space |
examples/lqr_control.py |
LQR cart-pole balancing (linearization + Riccati) |
examples/impedance_control.py |
Compliant end-effector (spring-damper behavior) |
examples/locomotion_controller.py |
Hopper FSM locomotion (finite state machine) |
examples/pick_and_place.py |
Gripper pick-and-place with waypoint sequencing |
examples/record_playback.py |
Save/load trajectories (record & replay) |
mujoco_base.py provides a minimal base class for building custom simulations:
from mujoco_base import MuJoCoBase
class MySim(MuJoCoBase):
def reset(self):
pass # set initial conditions
def controller(self, model, data):
data.ctrl[0] = ... # your control logic
sim = MySim("my_model.xml")
sim.run() # interactive viewer
# or
frames = sim.run_headless(duration=5.0) # offscreenStep-by-step Jupyter notebooks (run in Colab or locally):
| Notebook | Topic |
|---|---|
tutorial/00_what_is_mujoco.ipynb |
Start here! What MuJoCo is, mental model, first simulation |
tutorial/quickstart.ipynb |
Zero-install quickstart (Colab-ready) |
tutorial/01_basics.ipynb |
MjModel, MjData, named access |
tutorial/02_rendering.ipynb |
Rendering, cameras, scenes |
tutorial/03_simulation.ipynb |
Time stepping, mj_step, mj_forward |
tutorial/04_control.ipynb |
Actuators, PD control, callbacks |
tutorial/05_contact.ipynb |
Collision, contacts, force sensing |
tutorial/06_xml_modeling.ipynb |
MJCF modeling guide |
tutorial/07_mjx.ipynb |
MJX: GPU-parallel simulation with JAX |
tutorial/08_gymnasium.ipynb |
MuJoCo + Gymnasium for RL |
tutorial/09_sensors_and_estimation.ipynb |
Sensors, IMU, noise, state estimation |
tutorial/10_troubleshooting.ipynb |
Common errors & how to fix them |
tutorial/interactive_control.ipynb |
🎮 Interactive PD tuning with sliders |
| Concept | Description |
|---|---|
| MJCF | MuJoCo's XML format for defining models (docs) |
MjModel |
Compiled model (static) — physics parameters, geometry |
MjData |
Simulation state (dynamic) — positions, velocities, forces |
mujoco.viewer |
Built-in interactive 3D viewer |
mujoco.Renderer |
Offscreen rendering for headless environments |
| MJX | JAX backend for GPU-parallel simulation (docs) |
- Official MuJoCo Documentation
- MuJoCo GitHub
- Gymnasium MuJoCo Environments
- MuJoCo Menagerie — collection of robot models
- MJX Tutorial — GPU-accelerated simulation
Once you've completed these tutorials, explore:
| Resource | What you'll learn |
|---|---|
| MuJoCo Menagerie | Production-quality robot models (Franka, UR5e, Unitree, etc.) |
| dm_control | DeepMind's control suite — benchmarks for continuous control |
| Gymnasium Leaderboard | Standard RL benchmarks (HalfCheetah, Humanoid, Ant) |
| Brax | Differentiable physics in JAX (alternative to MJX) |
| MuJoCo XLA (MJX) Paper | Technical details of GPU-parallel MuJoCo |
| Robosuite | Manipulation benchmarks built on MuJoCo |
| IsaacLab | NVIDIA's sim framework (comparison point) |
- Fork this repository
- Create a new example in
examples/with inline MJCF or an XML inxml/ - Submit a pull request
See CONTRIBUTING.md for details.
MIT — free to use without restrictions.