MuJoCo: Physics Engine for Robotics and RL Research
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_stepruns 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
flexelement models 1D rods and cables, 2D cloth and shells and 3D soft bodies; theflexcompmacro 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.rolloutruns 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 samemjModelandmjDatastructures. - 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
simulateviewer 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.studioandmujoco.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.
| Check | Result |
|---|---|
pip install mujoco | Pulled 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-core | Only mujoco-core and NumPy; 29 MB installed. The cp312 Linux x86-64 wheel on PyPI is 9.7 MB |
| Version calls | mujoco.__version__ and mj_versionString() both returned 4.0.1 |
Compile hello.xml | 1.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 mass | 48 kg, inferred from geom volume (0.2 x 0.4 x 0.6 m) at the default density of 1000 |
| 10 simulated seconds | 5,000 steps in 0.018 s wall time, about 280,000 steps per second from a Python loop |
| First contact | At 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 state | Box 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.xml | nq=15, nv=13, 5 bodies, 6 joints, 4 geoms, 1 tendon, 2 sites |
Integrators on example.xml, 10 s | Euler about 137,000 steps/s, implicitfast about 130,000, RK4 about 52,000 (loop includes per-step checks) |
| Tendon limit | Active 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 steps | 1 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, default | mujoco.Renderer raised FatalError: "an OpenGL platform library has not been loaded into this process" |
Offscreen rendering, MUJOCO_GL=egl | Worked through Mesa's EGL; about 16 frames per second at 640 x 480 with software rendering |
MUJOCO_GL=osmesa | Failed inside PyOpenGL ('NoneType' object has no attribute 'glGetError'); no OSMesa library on the VM |
Rendering with mujoco-core only | ImportError: "Ensure that 'glfw' and 'pyopengl' are installed"; mujoco.viewer requires glfw; mujoco.studio absent |
mujoco-studio --gfx=web example.xml | Served 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 MJB | 1,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
speculativeenable 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-studioand themujocometapackage. 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
cableplugin andcompositeelement removed in favour of 1Dflexcomp, 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.
| Project | What its sources say it is | Licence | Python route | Relation to MuJoCo |
|---|---|---|---|---|
| MuJoCo | General-purpose physics engine for articulated structures with contact; C API, MJCF models | Apache-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." | zlib | pybullet on PyPI; latest 3.2.7, uploaded 30 January 2025 | General-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 compiler | Apache 2.0 | genesis-world on PyPI, Python 3.12 to 3.14; PyTorch installed first | Its README imports MJCF and lists MuJoCo as a "Reference for rigid body dynamics" |
| O3DE | Real-time 3D engine for "AAA games, cinema-quality 3D worlds, and high-fidelity simulations" | See its LICENSE files | Not a Python simulation library | Engine 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 (
qposversusqvelsizes, 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 tomujoco.FatalError, but custom C error handlers must not return to MuJoCo. - Web viewer is a development tool. The Studio docs say
WebViewerserves 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.1mujoco-corewheels on PyPI are taggedmanylinux_2_27/manylinux_2_28, so very old distributions may need to build from source; prebuilt Windows binaries are x86-64 only. The tip ofmain"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.
Repository:https://github.com/google-deepmind/mujoco
GitHub - google-deepmind/mujoco: MuJoCo: Physics Engine for Robotics and RL Research
MuJoCo is Google DeepMind's Apache-2.0 physics engine for articulated bodies with contact, used across robotics and RL. A hands-on look at 4.0.1: MJCF models, P...
github - google-deepmind/mujoco
Related Projects
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.
[](https://techloghub.com/open-source/mujoco?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)