MuJoCo
New1. Overview
MuJoCo stands for Multi-Joint dynamics with Contact. It is a general-purpose physics engine for robotics, biomechanics, graphics and animation, and machine learning, built for fast and accurate simulation of articulated structures interacting with their environment. It was initially developed by Roboti LLC, acquired and made freely available by Google DeepMind in October 2021, and open sourced in May 2022. For a physics-AI practitioner the engine is not background plumbing: it generates the trajectories a policy trains on, shapes the state distribution at every contact event, and defines the physical contract behind any claim that a simulated result is defensible. The formulation chosen for contact propagates all the way into trajectory optimisation, system identification, policy convergence and the final sim-to-real gap. This site already covers the GPU kernel substrate in Warp and the upper motion-learning layer in ProtoMotions; this entry documents the physics core that both of them consume.
MuJoCo 4.0, released on 6 November 2026, is the first major version since 3.0 whose middle version number marks breaking changes. It introduces MuJoCo Studio with Filament rendering, native deformables and elasto-plasticity, and speculative contacts. Version 4.0.1 followed on 11 November 2026 with a fix for a sparse Cholesky defect introduced in 4.0.0. For a team selecting or upgrading a simulator, this means both a substantially wider capability envelope and a need to re-check model files, Python package structure and every benchmark number recorded under 3.x. After reading this guide you should be able to answer four questions: what the soft convex contact model actually promises; which capabilities the C CPU kernel, the JAX-based MJX path and the GPU-oriented MuJoCo Warp path each cover; when batch parallelism is worth the resulting feature gaps; and what a 3.x migration and a per-asset licence review require.
All version, licence and capability statements below were checked on 12 November 2026 against the repository README, the documentation overview, the official changelog and the MuJoCo 4 announcement. Throughput and speed-up figures published by the project or quoted in the press are treated as self-reported or second-hand numbers, with their hardware, task and provenance recorded in Sections 6 and 9. This site does not certify those numbers for your workload. The physics simulation primer supplies the vocabulary for coordinates and solvers, and the classical solver cost boundary guide frames the comparison with conventional solvers.
2. How It Works
The central design decision is the combination of generalised coordinates with optimisation-based contact dynamics. Robotics and biomechanics engines traditionally use efficient recursive algorithms in joint coordinates, but they either omit contact or fall back to spring-damper models that demand very small timesteps. Game engines solve an optimisation problem for contact forces, yet commonly work in an over-specified Cartesian representation where joint constraints are enforced numerically and can drift or destabilise elaborate kinematic trees. MuJoCo pioneered the combination of the two: joint constraints remain implicit in the coordinate representation, while contact forces come from an optimisation problem. The documentation states that this combination has since been adopted by other simulators.
The second decision concerns the contact problem itself. Conventional modern formulations express frictional contact as a linear or non-linear complementarity problem, both of which are NP-hard. MuJoCo uses a different physical formulation that reduces to a convex optimisation problem. Its soft, convex and analytically invertible contact model allows soft contacts alongside joint, tendon and equality constraints, and gives inverse dynamics a uniquely defined solution, which is what makes data analysis, control synthesis and gradient-based optimisation tractable. The default Newton solver converges quadratically; conjugate gradient and a projected Gauss-Seidel solver handling elliptic friction cones are available as alternatives. The practical consequence is that a contact-rich step has a well-behaved gradient and a well-defined inverse, which is the property MJX and differentiable-physics tutorials exploit.
The runtime is a C and C++ library exposing a C API. Models are written in MJCF, a human-readable XML scene description language, and URDF files can also be loaded. The XML loader builds an mjSpec intermediate representation and compiles it into the low-level mjModel structure; working memory is preallocated in mjData, so the stepper does not allocate at runtime. The top-level mj_step function advances the full forward dynamics, and a large set of flags lets a caller run selected parts of the pipeline for control, estimation or sampling. Models can describe three-dimensional tendon geometry, abstract actuators with transmission, force generation and internal dynamics, and a wide range of sensors. Release 4.0 adds speculative contacts that keep fast convex geoms from tunnelling through thin obstacles within one timestep, elasto-plasticity with permanent deformation state stored in mjData.plastic, implicit deformable solids, shells and rods, constraint islands enabled by default with sleeping and multi-threaded collision and solve, and native convex collision with multi-point contacts. The physics simulation primer explains the modelling choices behind these stages, and Warp covers the GPU kernel layer used by the accelerated backends.
3. Scope and Assumptions
The first boundary is the physics domain. MuJoCo simulates articulated rigid bodies, contacts, tendons, actuators and, since 4.0, deformable solids, shells and rods. It is not a continuum-field solver for fluid flow, heat transfer or electromagnetism, and a project whose deliverable is a validated field solution belongs with OpenFOAM or PhysicsNeMo instead. The second boundary is the modelling contract: the soft contact model is a deliberate approximation of physical reality. Softness is what makes the optimisation convex and the inverse unique, and the documentation is explicit that complementarity must be violated for soft materials in reality. Treating the solver output as a certified measurement of a real contact force requires separate calibration of contact parameters, friction coefficients and actuator dynamics.
The third boundary is the execution backend. The C CPU kernel is the reference implementation and the stable contract. MJX reimplements MuJoCo in JAX for batched GPU and TPU execution with differentiable physics. MuJoCo Warp, maintained jointly by Google DeepMind and NVIDIA, targets NVIDIA GPUs through the Warp kernel language. These are not interchangeable: the MuJoCo Warp README describes the project as Beta and mostly feature complete while still requiring performance work, documentation and testing, states that differentiability through Warp is not currently available, restricts the Jacobian format to dense without islanding, and lists unsupported solvers, integrators and sensor cases. A plan that assumes a model can move from CPU to MJX to Warp with identical behaviour needs an explicit equivalence test, and the classical solver cost boundary guide is a useful reminder that cost comparisons depend on what is being delivered.
The fourth boundary is operational and legal. Release 4.0 splits the Python distribution into a minimal mujoco-core, an optional mujoco-studio and the default mujoco package that installs both; upgrading from 3.x requires uninstalling the old package first. Breaking changes in 4.0 alter sidesite tendon semantics, make RK4 integration fourth-order accurate for ball and free joints, and remove the cable plugin and the composite element in favour of one-dimensional flexcomp. Source code is Apache-2.0, but documents, images and videos in the doc directory are CC BY 4.0, the box-collision code carries a separate copyright notice, and the repository states plainly that this is not an officially supported Google product. Bundled models such as those in MuJoCo Menagerie and third-party bindings carry their own terms, so a commercial deployment needs a per-asset licence review.
4. Getting Started
The zero-install entry point is the browser. The project site hosts an interactive 4.0 showcase, and live.mujoco.org runs the WebAssembly build of MuJoCo Studio so an MJCF, MJB or MJZ file can be dragged in and inspected locally. The README notes that the WebAssembly path is slower than native C, which makes it a good inspection tool and a poor benchmark environment. For a local installation, prebuilt binaries cover Linux x86-64 and AArch64, Windows x86-64 and macOS universal. Python users install the bindings with pip install mujoco, which ships a copy of the engine inside the wheel; the README specifies Python 3.11 or newer and manylinux2014 for Linux wheels. A headless training node can install mujoco-core alone, keeping the dependency set close to NumPy plus the C library.
The repository provides a deliberate tutorial sequence. The introductory notebook covers the basic data structures and stepping loop; the model-editing notebook teaches procedural construction through mjSpec; the rollout notebook shows the multi-threaded rollout module; the LQR notebook synthesises a controller that balances a humanoid on one leg; the least-squares notebook introduces the Python non-linear solver; the MJX notebook moves the same model into JAX; and the differentiable-physics notebook trains locomotion policies with analytical gradients of the physics step. Working through that order is cheaper than starting from a training script, because it separates model authoring, stepping and batching before any of them can be confused with one another. The Python robotics entry and the physics-AI learning path place these steps in a broader sequence, and JAX documents the array library that MJX builds on.
Before trusting any result, fix the engine version, timestep, integrator, solver and contact parameters, and record them next to the measurement. A first disciplined experiment is a cross-backend comparison: run the same model and the same policy on the CPU kernel and on MJX, and treat any divergence as a property of the portability assumption until it is explained. Robot models can be pulled from MuJoCo Menagerie, which the 4.0 announcement lists at roughly seventy models, or from RoboCasa style asset collections. When upgrading from 3.x, uninstall first and re-run the model through a known trajectory, since the 4.0 breaking changes can alter tendon lengths, orientation integration and flexible-body state layout without producing an error message.
5. Comparison with Alternatives
The comparison that matters is by contract, not by leaderboard. Against GPU-native platforms such as Isaac Lab and Isaac Sim, the trade is between large-scale parallel throughput and the analytical predictability of a soft convex contact solver. Press comparisons quote roughly 150 thousand environment steps per second for 4096 humanoid environments on an RTX 4090 with Isaac Lab against roughly 75 thousand for MJX on the same hardware; those numbers are workload-specific and second-hand, and they describe throughput, not contact fidelity. A team optimising pure sample throughput and a team validating a dexterous grasp are solving different problems, and the NVIDIA company report gives the wider platform context.
Against other general-purpose rigid-body engines, the useful distinction is representational. Engines using Cartesian coordinates with numerically imposed joint constraints and engines using generalised coordinates with spring-damper contacts make different accuracy and stability compromises under elaborate kinematic trees. MuJoCo's choice of a convex, analytically invertible contact model is a third position. This guide does not rank the three: each is a different approximation of real contact, and the official documentation itself frames the soft and complementarity formulations as two approximations of physical reality. OpenFOAM sits further away again, because its subject is continuum fields rather than articulated mechanisms.
Inside the MuJoCo ecosystem the relationships are layered. MJX and MuJoCo Warp are execution backends for MuJoCo physics, not competing engines; the Warp entry covers the kernel substrate that Warp builds on. Newton is a Linux Foundation project initiated by NVIDIA, Google DeepMind and Disney Research that uses MuJoCo Warp as a primary physics backend and plugs into Isaac Lab, MuJoCo Playground and mjlab. ProtoMotions is an upper-layer humanoid motion-learning framework that consumes MuJoCo as one of its simulator backends and standardises its robot assets on MuJoCo XML. Choosing among these is a question of which layer your team owns: the contact model, the batch execution, the orchestration or the learning task.
6. Benchmarks and Evidence
The largest public evidence base is operational scale rather than accuracy. The official MuJoCo 4 announcement of 7 November 2026 reports about 3.6 million PyPI downloads per month, more than 16 thousand GitHub stars, 39 releases since 3.0, and more than 45 external contributors submitting roughly two thousand commits in the previous year. It also states that MuJoCo Playground 1.0 shipped alongside MuJoCo 4. Third-party trackers quote star counts between 17.2 and 17.6 thousand at various dates in November 2026; these come from different crawlers and dates and are not merged into the official figure here. A direct re-check on 16 November 2026 records 18,125 stars, 5,467,587 PyPI downloads in the preceding month and 42 releases since 3.0. Scale metrics show adoption, not physical correctness.
Release 4.0 supplies concrete capability demonstrations. The speculative-contact feature is described with a benchmark in which a robot arm catches a 0.7 millimetre playing card falling faster than two metres per second at a 16 millisecond timestep, where conventional discrete collision detection misses the card beyond an 8 millisecond timestep; press coverage of the release reports six to nine times faster simulation for stair climbing and thin-object grasping because smaller substeps are no longer needed. The same coverage reports one-dimensional elastic rod bending and torsion within half a percent of Euler-Bernoulli cantilever theory on CPU and MuJoCo Warp. These are project demonstrations or press transcriptions of them, tied to specific models and hardware, and should be reproduced locally before appearing in a proposal.
GPU acceleration figures have a similar provenance. Coverage of the Newton 1.0 general availability announcement at NVIDIA GTC on 17 March 2026 quotes MuJoCo Warp at 252 times MJX on locomotion tasks and 475 times on manipulation tasks on an RTX PRO 6000 Blackwell GPU. The MuJoCo Warp README, by contrast, describes Beta status and remaining performance work. No independent blind benchmark comparing contact accuracy across engines is cited here, and the 4.0.1 fix for a sparse Cholesky factorisation defect in 4.0.0, which could cause slow convergence, wrong accelerations and divergence, is a concrete demonstration that solver version belongs in every recorded result. The classical solver cost boundary guide gives the discipline for recording those conditions.
7. Role in Physics-AI Workflows
In a physics-AI programme MuJoCo occupies the layer where an environment becomes reproducible physics. During data generation it produces trajectories whose contact events are governed by a documented, convex model rather than by an undocumented numerical shortcut, which matters when those trajectories become training labels. During policy training, batch backends such as MJX and MuJoCo Warp make thousands of parallel environments affordable, while the CPU kernel remains the reference against which a batch result is checked. During sim-to-real calibration, the same model can be re-run with different contact parameters, actuator delays and sensor noise, and the 4.0 release adds a system-identification toolbox to that workflow. The physics-AI learning path orders these stages, and the physics simulation primer explains the modelling assumptions behind each one.
Differentiability is a second role. Because the contact problem is convex and has a uniquely defined inverse, analytical gradients of the physics step are available, and the repository ships a tutorial that trains locomotion policies with them. That supports trajectory optimisation, system identification and short-horizon policy improvement, provided the user remembers that a gradient of a model is a gradient of the model, not of the physical robot. JAX and Warp document the two execution substrates that make these workflows practical at scale.
The third role is as a shared asset and evaluation contract. MuJoCo Menagerie provides a common robot model library, and frameworks such as ProtoMotions standardise on MuJoCo XML so that one asset file can serve several backends. This is why the engine appears so often as a first evaluation environment for learned robot policies: a common model format makes results comparable across teams. The RoboCasa and MuJoCo Menagerie entries show the asset side of that arrangement, and Python robotics covers the tooling that connects a policy to a real controller.
8. Limitations and Failure Modes
The most common failure is treating a soft contact model as a measured contact law. Parameters governing constraint softness, friction and solver tolerance are modelling choices; a policy tuned to one set can fail on hardware whose friction, compliance and actuator dynamics differ. Domain randomisation and system identification reduce this gap but do not close it, and no release note claims otherwise. A second failure mode is timestep selection: before speculative contacts, fast or thin objects demanded smaller steps or inflated margins, and the 4.0 feature currently covers convex primitives and meshes on CPU, with heightfields, signed distance fields, flex and the GPU backends listed as follow-up work. Assuming coverage across every geometry and backend would be a misreading of the changelog.
Migration is a third failure mode. The 4.0 breaking changes alter tendon sidesite semantics, RK4 orientation integration and flexible-body state layout; the cable plugin and composite element are removed; and the Python package split requires an explicit uninstall when upgrading from 3.x. A model that loads without error may still produce different tendon lengths or different rolling behaviour. A fourth concerns backend capability: the MuJoCo Warp README lists missing differentiability, dense-only Jacobians, unsupported solvers and integrators, and incomplete sensor and flex cases, while MJX has its own feature coverage limits. Cross-backend equivalence has to be measured rather than assumed.
Two boundaries are easy to miss. Rendering and physics are separate axes: Filament physically based rendering, HDR lighting and browser streaming in MuJoCo Studio improve visual inspection but do not change the contact solve, and a visually convincing scene is not evidence of physical fidelity. Licensing is equally granular: source code is Apache-2.0, documentation assets are CC BY 4.0, box-collision code carries a separate notice, bundled robot models and third-party bindings have their own terms, and the repository states it is not an officially supported Google product. A deployment that reviews only the top-level licence has not finished its compliance work. Section 9 records the source of each of these statements, and Warp supplies the kernel-level context for the GPU caveats.
9. Version and Source Notes
Record one: the academic origin is the 2012 IROS paper by Todorov, Erez and Tassa, cited in the repository README; the documentation overview states that Roboti LLC developed MuJoCo initially, that Google DeepMind acquired it and made it freely available in October 2021, and that it was open sourced in May 2022. The year field on this entry uses the 2022 open-source release; descriptions that call DeepMind the original developer conflate the current maintainer with the original author. Record two: on 16 November 2026 the GitHub release page labels 4.0.1 of 11 November 2026 as Latest, so the earlier state in which 4.0.0 of 6 November 2026 still carried the Latest label no longer holds. For a new deployment, 4.0.1 or newer is the safer baseline because of the Cholesky fix: the 4.0.1 release notes record a sparse Cholesky factorisation bug introduced in 4.0.0 that merged rows with different descendants into one supernode and gave the Newton solver a wrong Hessian factor when the constraint Jacobian is sparse, causing slow convergence, wrong accelerations and divergence.
Record three: the README specifies Python 3.11 or newer, the 4.0 announcement describes support through Python 3.15 including free-threaded builds, and third-party archives sometimes state 3.10 or newer. The repository README governs the installation statement on this page. Record four: the official announcement reports more than 16 thousand GitHub stars and about 3.6 million monthly PyPI downloads, while external trackers quote 17.2 to 17.6 thousand stars at different dates. Only the official magnitude is used in Section 6. A re-check on 16 November 2026 gives 18,125 stars, 5,467,587 PyPI downloads in the last month and 42 releases since 3.0, split into 40 in the 3.x line and 2 in the 4.x line. Record five: MuJoCo Playground 1.0 shipped with MuJoCo 4, and Newton is described in the announcement as joint work with NVIDIA, Disney Research and TRI under the Linux Foundation.
Record six: all throughput, speed-up and accuracy figures in Section 6 are project demonstrations or press transcriptions tied to named hardware and tasks, including the GTC Newton figures and the RTX 4090 comparison; no independent reproduction is claimed. Record seven: the licence split, the separate box-collision copyright, the per-asset terms of bundled models and the absence of official Google product support all come from the repository README and are recorded without consolidation. Record eight: the 4.0 breaking-change list, the Python package split and the 4.0.1 bug fixes come from the official changelog. Statements were checked on 12 November 2026, with the release label, the star count, the download count and the release count re-checked on 16 November 2026; a later release should trigger a fresh pass over Sections 3, 6 and 8 before this entry is cited in a customer document.
10. References
- Google DeepMind, MuJoCo repository README, github.com/google-deepmind/mujoco, overview, installation, bindings, citation and licence notices.
- MuJoCo Documentation, Overview, mujoco.readthedocs.io, history, C API, MJCF, URDF, generalised coordinates and soft convex contact.
- MuJoCo Documentation, Changelog, versions 4.0.1 (11 November 2026) and 4.0.0 (6 November 2026), breaking changes and bug fixes.
- Google DeepMind, MuJoCo 4.0.0 GitHub release notes, 6 November 2026, speculative contacts, elasto-plasticity and Python package split.
- Yuval Tassa, MuJoCo 4: Studio & Filament, Deformables, Speculative Contacts, GitHub discussion 3773, 7 November 2026.
- Todorov E., Erez T., Tassa Y., MuJoCo: A Physics Engine for Model-Based Control, 2012 IEEE/RSJ IROS, DOI 10.1109/IROS.2012.6386109.
- MuJoCo Documentation, MuJoCo XLA (MJX) chapter and the MJX tutorial notebook in the repository.
- MuJoCo Documentation, Computation chapter, convex contact formulation, solvers and inverse dynamics.
- Google DeepMind and NVIDIA, MuJoCo Warp repository README, Beta status, feature compatibility table and benchmarking tools.
- Newton Physics project documentation, Linux Foundation hosting, founding partners and MuJoCo Warp backend integration.
- Google DeepMind, MuJoCo Menagerie robot model repository and the mujoco-menagerie Python package.
- Google DeepMind, dm_control and MuJoCo Playground 1.0, environment stack and robot learning suite.