MuJoCo: Physics Engine for Robotics and RL Research
GitHub Repo
Apache-2.0
November 16, 2026 at 01:54 PM
0 views

MuJoCo: Physics Engine for Robotics and RL Research

@google-deepmindProject Author

What MuJoCo is

MuJoCo stands for Multi-Joint dynamics with Contact. The README calls it "a general purpose physics engine that aims to facilitate research and development in robotics, biomechanics, graphics and animation, machine learning, and other areas which demand fast and accurate simulation of articulated structures interacting with their environment." It is a C/C++ library with a C API, maintained by Google DeepMind, with first-party Python bindings, JavaScript/WebAssembly bindings and a C# plug-in for Unity. It sits underneath a lot of robotics and reinforcement learning tooling: the README describes MuJoCo as "the backbone for numerous environment packages", and Google DeepMind's own dm_control stack depends on the mujoco Python package.

The project has a longer history than its GitHub repository. The overview chapter of the documentation says MuJoCo was initially developed by Roboti LLC, acquired and made freely available by Google DeepMind in October 2021, and open sourced in May 2022. The repository was created on 27 August 2021, its source code is under the Apache License 2.0, and the reStructuredText documentation, images and videos under doc/ are under CC BY 4.0. The README adds the usual line that "this is not an officially supported Google product".

The intended audience is stated plainly: MuJoCo "is intended for researchers and developers". The documentation lists model-based uses such as control synthesis, state estimation, system identification, mechanism design, inverse-dynamics data analysis and "parallel sampling for machine learning applications", and adds that it can also serve "as a more traditional simulator, including for gaming and interactive virtual environments". In practice most users meet it as the simulator under robot-learning benchmarks, as a test bed for controllers, or as the physics behind biomechanics models of muscles and tendons.

How it works: MJCF, mjModel and mjData

From XML to a compiled model

Models are written in MJCF, MuJoCo's own XML scene description format; URDF files can also be loaded. A built-in compiler turns the XML into a low-level C struct, mjModel, which is "cross-indexed and optimized for runtime computation". There is also an in-memory high-level representation, mjSpec, which maps one-to-one to MJCF and can be built or edited from code and then compiled. A compiled model can be saved as a binary MJB file, but the overview warns that MJB files "are version-specific and cannot be decompiled, thus models should always be maintained as XML files or packaged into MJZ archives". MJCF leans on a defaults mechanism that the docs compare to CSS, so most attributes (masses, inertias, friction, collision rules, the time step) can be left out and inferred.

Model and data are separate

At runtime MuJoCo keeps two structs apart. mjModel holds the model description and is expected to stay constant. mjData holds every dynamic variable and intermediate result, plus a preallocated internal stack, so "the runtime module does not need to call memory allocation functions after the model is initialized". Every top-level function follows the pattern mj_step(const mjModel* m, mjData* d). The overview points out what this buys: many mjData instances can share one mjModel and run on separate threads for sampling or finite differences.

Generalized coordinates plus convex contact

The documentation's main technical claim is about how contact is computed. Robotics engines traditionally simulate in joint (generalized) coordinates but handle contact with stiff springs; game engines solve for contact forces as an optimization problem but represent bodies in over-specified Cartesian coordinates. MuJoCo, in the docs' words, "pioneered the combination of simulation in generalized coordinates with optimization-based contact dynamics". Its contact model reduces to a convex optimization problem rather than an NP-hard complementarity problem, allows soft contacts, and has a uniquely defined inverse, which matters for inverse dynamics and control. The default solver is Newton, with conjugate gradient and projected Gauss-Seidel alternatives. The docs also warn that users accustomed to game engines "may find the generalized coordinates counterintuitive at first".

Key features

  • Tendons and actuators. Spatial tendons are minimum-length strings with wrapping and via points (the docs compare the mechanism to OpenSim's, with a more restricted closed-form set). The abstract actuator model covers motors, pneumatic and hydraulic cylinders, PD controllers and biological muscles.
  • Reconfigurable pipeline. mj_step runs the full forward dynamics, but flags and lower-level functions let callers run only parts of the pipeline, and callbacks can add custom force fields, actuators, collision routines and controllers.
  • Deformables. The flex element models 1D rods and cables, 2D cloth and shells and 3D soft bodies; the flexcomp macro expands meshes, grids and parametric shapes into bodies, joints and flex elements.
  • Constraint islands and sleeping. The solver finds independent groups of constrained bodies, solves each with the iterations it needs, and can freeze islands that are at rest.
  • Engine plugins. Sensors, actuators and passive forces can be added as dynamically loaded shared libraries without changing the core engine.
  • Batched and GPU back ends. mujoco.rollout runs multithreaded rollouts on CPU. MJX provides a JAX API and MuJoCo Warp (MJWarp), developed jointly by NVIDIA and Google DeepMind, targets NVIDIA GPUs. Both consume the same mjModel and mjData structures.
  • MuJoCo Studio. A newer visualization SDK for C++ and Python built on Filament physically based rendering, Dear ImGui panels and plugins. It runs as a desktop app, in the browser at live.mujoco.org via WebAssembly, or as a headless web viewer attached to a Python simulation. The classic OpenGL renderer and the simulate viewer remain.
  • Python modules beyond the bindings. The package ships mujoco.rollout, mujoco.batch, mujoco.minimize (a nonlinear least-squares solver), mujoco.sysid (system identification), mujoco.studio and mujoco.usd (OpenUSD import and export).
  • Agent skill files. Since 4.0.0 the Python package bundles the Sphinx manual and a set of agent SKILL files under mujoco/doc/, described in the Studio docs as "idiomatic API patterns and common pitfalls for both developers and AI coding assistants".

Getting started

The README offers three entry points: try models in the browser at mujoco.org or live.mujoco.org, download a prebuilt release (Linux x86-64 and AArch64, Windows x86-64, macOS universal) and run MuJoCo Studio or simulate, or use Python. The Python bindings need Python 3.11 or newer and bundle their own copy of the library:

pip install mujoco

Since 4.0.0 mujoco is a metapackage. On a headless server or an RL training node, the Python docs suggest the core package, which depends only on NumPy:

pip install mujoco-core

The overview's smallest model is a plane and a free-floating box. Saved as hello.xml, it is enough to see contact working:

<mujoco>
  <worldbody>
    <light diffuse=".5 .5 .5" pos="0 0 3" dir="0 0 -1"/>
    <geom type="plane" size="1 1 0.1" rgba=".9 0 0 1"/>
    <body pos="0 0 1">
      <joint type="free"/>
      <geom type="box" size=".1 .2 .3" rgba="0 .9 0 1"/>
    </body>
  </worldbody>
</mujoco>

In Python the pattern is to compile with mujoco.MjModel.from_xml_path() or from_xml_string(), create mujoco.MjData(model), and call mujoco.mj_step(model, data) in a loop. The batched API documented for mujoco.rollout takes arrays of initial states and controls:

state, sensordata = rollout.rollout(model, data, initial_state, control)

To look at a running simulation on a remote machine, the Studio documentation shows a headless web viewer:

python -m mujoco.studio.viewer --model=humanoid.xml --gfx=web

GPU users install the JAX-based MJX package separately:

pip install mujoco-mjx

Hands-on: MuJoCo 4.0.1 on a 2-vCPU Linux VM

MuJoCo 4.0.1 was installed from PyPI on 16 November 2026 into two fresh Python 3.13 virtual environments on a cloud VM with two vCPUs (Intel Xeon at 2.30 GHz), no GPU and no display. Both models from the overview chapter were run: hello.xml above and the 7-degree-of-freedom example.xml arm holding a cylinder on a length-limited tendon. Timings are single runs of short loops, so read them as orders of magnitude, not benchmarks.

CheckResult
pip install mujocoPulled mujoco, mujoco-core, mujoco-studio and mujoco-studio-wasm 4.0.1 plus glfw 2.11.0, PyOpenGL 3.1.10, websockets and NumPy 2.5.5; the installed mujoco directory is 51 MB (the bundled libmujoco.so.4.0.1 is 7.3 MB, the Studio module 22 MB, the bundled docs 2.6 MB)
pip install mujoco-coreOnly mujoco-core and NumPy; 29 MB installed. The cp312 Linux x86-64 wheel on PyPI is 9.7 MB
Version callsmujoco.__version__ and mj_versionString() both returned 4.0.1
Compile hello.xml1.3 ms; nq=7, nv=6 (a free joint has a 7-number quaternion position and 6 velocities), 2 bodies, 2 geoms; defaults: time step 0.002 s, Euler integrator, Newton solver, pyramidal friction cones
Box mass48 kg, inferred from geom volume (0.2 x 0.4 x 0.6 m) at the default density of 1000
10 simulated seconds5,000 steps in 0.018 s wall time, about 280,000 steps per second from a Python loop
First contactAt t = 0.38 s with 4 contacts (the box corners), matching free fall over 0.7 m; 4 contacts at the end, no warnings
Resting stateBox centre at z = 0.29989 m, so the corners sit about 0.1 mm inside the plane (soft contact); the four normal forces from mj_contactForce summed to 470.88 N, equal to the box weight
Compile example.xmlnq=15, nv=13, 5 bodies, 6 joints, 4 geoms, 1 tendon, 2 sites
Integrators on example.xml, 10 sEuler about 137,000 steps/s, implicitfast about 130,000, RK4 about 52,000 (loop includes per-step checks)
Tendon limitActive on about 4,830 of 5,000 steps; final length 0.6037 against a range of 0 to 0.6, i.e. a soft limit stretched by about 4 mm
mujoco.rollout, 64 rollouts x 1,000 steps1 thread: 0.255 s (about 251,000 steps/s); 2 threads: 0.136 s (about 471,000 steps/s); output array shape (64, 1000, 29); results bit-identical between 1 and 2 threads
Offscreen rendering, defaultmujoco.Renderer raised FatalError: "an OpenGL platform library has not been loaded into this process"
Offscreen rendering, MUJOCO_GL=eglWorked through Mesa's EGL; about 16 frames per second at 640 x 480 with software rendering
MUJOCO_GL=osmesaFailed inside PyOpenGL ('NoneType' object has no attribute 'glGetError'); no OSMesa library on the VM
Rendering with mujoco-core onlyImportError: "Ensure that 'glfw' and 'pyopengl' are installed"; mujoco.viewer requires glfw; mujoco.studio absent
mujoco-studio --gfx=web example.xmlServed the Studio page (HTTP 200, 26 KB of HTML) on the chosen port and printed "Warning: No authentication or encryption. Anyone who can reach this port can connect and see your logs and file paths."
mj_saveModel to MJB1,190,875 bytes, against 1,139 bytes of XML

Four things stood out. First, headless rendering does not work out of the box on a server: with no display, the default GLFW path fails with a FatalError, and the fix is to set MUJOCO_GL=egl (the bindings' gl_context.py accepts glfw, egl, osmesa and glx on Linux), which in turn needs a system EGL library. Second, the core-only install really is core-only: it is the right choice for training workers, but any code that renders frames needs mujoco-core[rendering] or the full package. Third, the MJB file was a thousand times larger than its XML, because the 256 x 256 gradient skybox in example.xml is stored as raw pixels; MJB is a cache, not a distribution format. Fourth, the contact numbers show the soft-contact model at work: bodies at rest interpenetrate slightly and limits stretch slightly, which is by design but can surprise anyone checking positions against exact geometry.

What changed in 4.0

MuJoCo 4.0.0 shipped on 6 November 2026 and 4.0.1 followed on 11 November 2026. Under the project's versioning scheme (a modified semantic versioning since 3.5.0), the first number is a "SUPERMAJOR" for "breaking changes and/or significant new features". The changelog's headline items for 4.0.0:

  • Speculative contacts. A new speculative enable flag stops fast-moving convex geoms from tunnelling through thin obstacles within one time step.
  • Elasto-plasticity. Joint and tendon springs can yield, and 2D and 3D flexes support continuum plasticity, with plastic state stored in mjData.plastic.
  • Split Python distribution. mujoco-core, mujoco-studio and the mujoco metapackage. The changelog warns that upgrading a pre-split install with pip needs an uninstall first or a forced reinstall, so pip does not remove files that moved.
  • Breaking engine changes. New tendon side-site semantics, RK4 now fourth-order for ball and free joint orientations, the cable plugin and composite element removed in favour of 1D flexcomp, corrected flex elastic constants (models become stiffer), and several previously accepted invalid models now rejected by the compiler. Each comes with migration notes.
  • Solver and rendering work. The changelog says sparse Newton is "1.4-3x faster" on flex models; Filament rendering gained per-geom shadow control, haze and skybox support.
  • Python 3.10 dropped, and the manual plus agent skills bundled in the package.

4.0.1 is a fix release, notably for a sparse Cholesky bug introduced in 4.0.0 that could give the Newton solver "slow convergence, wrong accelerations and divergence", and for simulate aborting at startup when one plugin library (the USD decoder in the 4.0.0 macOS and Linux archives) failed to load. Anyone on 4.0.0 has a concrete reason to move to 4.0.1.

How MuJoCo compares

MuJoCo's own documents do not benchmark against other simulators, so the table sticks to what each project's README or package metadata states. Two of the alternatives are robotics and ML simulators; the third is a general game engine that is sometimes considered for simulation work.

ProjectWhat its sources say it isLicencePython routeRelation to MuJoCo
MuJoCoGeneral-purpose physics engine for articulated structures with contact; C API, MJCF modelsApache-2.0 (code), CC BY 4.0 (docs)pip install mujoco, Python 3.11+; latest 4.0.1 (11 November 2026)Reference point
Bullet Physics / PyBullet"Real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc."zlibpybullet on PyPI; latest 3.2.7, uploaded 30 January 2025General-purpose engine aimed at games as well as robotics. Its README says the issue tracker "is closed until it is cleaned up"
Genesis World"A simulation platform for physical AI developments" with rigid, FEM, MPM, particle and other solvers plus its own renderer and compilerApache 2.0genesis-world on PyPI, Python 3.12 to 3.14; PyTorch installed firstIts README imports MJCF and lists MuJoCo as a "Reference for rigid body dynamics"
O3DEReal-time 3D engine for "AAA games, cinema-quality 3D worlds, and high-fidelity simulations"See its LICENSE filesNot a Python simulation libraryEngine with editor and rendering pipeline; MuJoCo is a library embedded in research code

The practical split is roughly this. For robot learning or controller research where accurate articulated dynamics, a documented contact model and a large existing ecosystem of MJCF models matter, MuJoCo is the default most environment packages already assume. Genesis World aims at a wider multi-physics scope (fluids, granular media, FEM) and GPU scaling inside one framework, and borrows from MuJoCo for rigid bodies; it is the one to evaluate if those solvers are the requirement, keeping in mind it started as an academic project in December 2024. PyBullet still installs and has a long publication history, but its latest PyPI release dates from January 2025, and MuJoCo's monthly-plus release pace is the more active of the two. Game engines such as O3DE or Stride make sense when the product is an interactive 3D application with an editor; they are a different category from a simulation library called from Python. For camera-based tasks, rendered frames from MuJoCo come back as NumPy arrays and can go straight into a vision library such as OpenCV, and rollout state arrays are easy to tabulate with pandas.

When not to use MuJoCo: limits and trade-offs

  • Not a game engine. There is no scene editor, asset pipeline or gameplay layer. MuJoCo Studio is a viewer and SDK for simulations, not a content tool.
  • Generalized coordinates take adjustment. The docs themselves warn that users from game engines may find them counterintuitive, and state layouts (qpos versus qvel sizes, quaternions for free and ball joints) need care.
  • No reproducibility across versions. Simulation is deterministic for a given version, but the versioning document says numerical reproducibility across versions "is never guaranteed". 4.0.0 alone changed RK4 results, flex stiffness, tendon wrapping and contact distribution. Pin the version for experiments that must be repeatable.
  • Breaking changes are routine. The versioning page notes that under strict semantic versioning "most MuJoCo releases are MAJOR", because the MJCF and mjSpec surface is large. Expect to read migration notes on upgrades.
  • Headless rendering needs setup. As the hands-on run showed, servers need MUJOCO_GL=egl (or OSMesa) and the matching system libraries; the core-only package has no rendering at all.
  • Fatal errors. Irrecoverable C-level errors go through mju_error, which terminates the process in C; the Python bindings convert them to mujoco.FatalError, but custom C error handlers must not return to MuJoCo.
  • Web viewer is a development tool. The Studio docs say WebViewer serves plain HTTP and WebSockets "without authentication or encryption" and "currently listens on all network interfaces"; use it on localhost or through an SSH tunnel.
  • CPU first, GPU via separate packages. The C engine is tuned for latency of a single step; the MJWarp docs say MJWarp trades per-step latency for throughput and is suited to large-scale sampling. GPU batching means MJX or MJWarp, with their own dependencies (JAX, NVIDIA Warp) and feature differences.
  • Platform and Python limits. Python 3.11 or newer only. The README says Linux wheels target manylinux2014, but the 4.0.1 mujoco-core wheels on PyPI are tagged manylinux_2_27/manylinux_2_28, so very old distributions may need to build from source; prebuilt Windows binaries are x86-64 only. The tip of main "may be unstable".

Project activity

Checked 16 November 2026: latest release 4.0.1 (11 November 2026, per the changelog and the PyPI package), Apache-2.0 licence, about 18,100 stars on the google-deepmind/mujoco repository, with around 2,200 forks and a push on 16 November 2026. The repository's primary language is C++, it was created on 27 August 2021 and develops on main. The README says the team aims to release "in the first week of each month", although autumn 2026 ran faster than that: 3.14.0 on 22 September, 3.15.0 on 5 October, 3.16.0 on 14 October, 3.17.0 on 22 October, then 4.0.0 and 4.0.1 in November. Documentation is at mujoco.readthedocs.io, with sources under doc/ in the repo; the homepage is mujoco.org. Questions go to GitHub Discussions, and issues are reserved for bugs and feature requests. Research use should cite the 2012 IROS paper by Todorov, Erez and Tassa listed in the README.

Enjoying this project?

Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.

Project
mujoco
Created
November 16
Last Updated
November 16, 2026 at 01:54 PM

Maintain MuJoCo: Physics Engine for Robotics and RL Research? Add the badge to your README

Show that the project is featured on TechLogHub and send readers to this write-up.

Featured on TechLogHub
[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/mujoco?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)

Find more projects like this

One email a week: new and trending developer tools, fresh comparisons, and what shipped. Unsubscribe in one click.