MuJoCo 4: Studio & Filament, Deformables, Speculative Contacts · google-deepmind mujoco · Discussion #3773

Three years ago, MuJoCo 3.0 introduced MJX, signed distance fields, constraint islands and early deformables. There have been 39 releases since then. MuJoCo now gets about 3.6 million PyPI downloads a month, has more than 16K GitHub stars, and in the past year more than 45 external contributors submitted around 2K commits. We have also been working with NVIDIA on MuJoCo Warp, and with NVIDIA, Disney, TRI and others on Newton (under the Linux Foundation).

Since 3.5, the middle version number simply marks breaking changes, so we saved 4.0 for a big step. Today we are releasing MuJoCo 4, together with MuJoCo Playground 1.0.

Getting Started

pip uninstall -y mujoco   # if upgrading from 3.x
pip install -U mujoco

To see the new features without installing anything, visit mujoco.org, which is now an interactive 4.0 showcase running in your browser, or open any model at live.mujoco.org. The Python package is now split into a minimal mujoco-core and optional components, and mujoco installs all of them. Samples and model/ scenes are omitted from the PyPI wheels to keep them small—expand the block below to run the same feature slideshow locally from a repo checkout.

# Upgrading from 3.x? Uninstall first (needed for mujoco and mujoco-core alike)
pip uninstall -y mujoco

# Everything: mujoco-core + mujoco-studio (Studio, Filament) + classic viewer
pip install -U mujoco

# Minimal headless install: engine, Python bindings, offscreen OpenGL; needs only numpy
pip install -U mujoco-core
pip install -U "mujoco-core[rendering]"  # adds glfw + pyopengl for mujoco.viewer

# Optional extras and the robot model library
pip install -U "mujoco[usd]"             # OpenUSD importer, exporter & schemas (Python 3.11–3.13)
pip install -U "mujoco[sysid]"           # system identification toolbox
pip install -U mujoco-menagerie          # ~70 robot models (mm.load / uvx mujoco-menagerie view <robot>)

# Interactive 4.0 feature slideshow
python -m mujoco.studio.viewer --gfx=web --plugins=python/mujoco/sample/studio/overview/slideshow_plugins.py

Then and Now

If you last looked closely at MuJoCo around 3.0, this is what changed. The changelog has the per-release details.

Pillar 1: MuJoCo Studio (mujoco.studio), Filament PBR & live.mujoco.org

For a decade, MuJoCo shipped a single fixed-function OpenGL 1.5 viewer (simulate / mjr, now in maintenance mode), and extending a monolithic viewer proved a poor fit for custom research tools. In 4.0, MuJoCo Studio graduates out of experimental/ with a modular, viewer-agnostic MuJoCo Studio SDK for Python and C++ at its core:

• Composable C++ & Python SDK: Standalone components for simulation, rich immediate-mode UIs built on Dear ImGui, and 3D rendering. In Python, Studio decouples physics from UI rendering via non-blocking message channels, and hot_reload live-swaps Python ViewerPlugin/SimPlugin code and MJCF files. Paired with shipped coding-agent skills, these lightweight, composable APIs make it easy to spin up custom visualizers and debug tools per experiment.
• Optional Studio App & Zero-Install Browser (live.mujoco.org): Built on top of the SDK, our new default interactive viewer (mujoco::studio::App in C++, studio_app.App in Python, and in the browser at live.mujoco.org with .xml, .mjb, and .mjz drag-and-drop plus ?model=github:<org>/<repo>/<branch>/<path> deep links) adds dockable light/dark workspaces, an integrated console, a 3D camera gizmo, and MjSpec inspection and editing. The Studio App is optional: in Python, studio_app.App() is just an ordinary plugin with no special status, so you can use it out of the box, extend it with your own plugins, or leave it out altogether to build a custom tool, like the feature slideshow that now powers mujoco.org.
• Share a live session (--gfx=web): Run Studio on a remote or GPU-less machine, open it in a browser, and share the session with colleagues. One browser at a time is the controller and drives the simulation and UI; everyone else watches the same session live as a spectator, and control can be handed over (WebViewer). The same tools and plugins also run as native desktop apps (NativeViewer), with no change to simulation or plugin code.
• Filament PBR (mjrf): Powers 3D rendering in the SDK and standalone offscreen views with metallic-roughness materials, HDR image-based lighting (<light type="image" texture="..."/>), soft area shadows, tone mapping/AO/bloom/fog post-processing, and asynchronous multi-camera RGB/depth/segmentation frame queues.

# Native desktop window or headless remote browser viewer (with live plugin & XML hot-reload)
python -m mujoco.studio.viewer --model=humanoid.xml --hot_reload=all
python -m mujoco.studio.viewer --model=humanoid.xml --gfx=web

from mujoco.studio import app as studio_app, launch_web  # or launch_native

# The following call blocks; for a non-blocking example, see
#   python/mujoco/sample/studio/custom_sim_loop.py
launch_web.run(
    model_path="humanoid.xml",
    plugins=[studio_app.App(), *studio_app.SIM_PLUGINS],
)

Try it: a humanoid in your browser.

Pillar 2: Deformables Have Matured

Soft bodies in MuJoCo 4.0 graduate from experimental plugins and explicit penalties to native continuum deformables solved implicitly alongside rigid bodies, joints, and tendons:

• Implicit discrete integrator: Folds passive damping and elasticity into the constraint solver's effective inertia (M_hat = M + h*D + h^2*K), keeping stiff servos, cables, thin shells and 3D solids stable at 5–10x larger timesteps (experimental large-strain Neo-Hookean solids are also available via MjSpec). Because cloth stretching is now integrated implicitly, the old flexvert equality workarounds are retired.
• Penetration-free IPC cloth: Barrier-free augmented-Lagrangian contact with continuous collision checks keeps 2D cloth intersection-free (bag_hoop.xml, poncho.xml).
• Plasticity: Joint and tendon springs yield permanently past springyield (wire.xml). 2D shells and 3D solids, including trilinear and quadratic cages, yield in stretching (von Mises J2) via <elasticity yield> (clay.xml, roller.xml, torsion.xml). Shells with elastic2d="bend" or "both" also yield in bending, so folded paper and metal foil keep their creases and dents (paper.xml, foil.xml). Plastic state lives in mjData.plastic and is saved with mjSTATE_PLASTIC.
• 1D elastic rods: dim="1" flexes are discrete elastic rods with bending and twist (section="circle|box", shear, curved rest shapes), matching Euler-Bernoulli cantilever deflection within 0.5% on both CPU and MuJoCo Warp (cable.xml, coil.xml, belt.xml). They replace <composite> and the cable plugin.
• Mesh cages and materials: trilinear and quadratic cages integrate stiffness and mass over the true mesh volume (Finite Cell Method), distribute contact forces with exact barycentric weights, take <mesh> assets directly (<flexcomp type="mesh" mesh="...">), and support per-element materials.

Several of these are a single attribute on an existing model:

<!-- cloth that never passes through the table -->
<option integrator="discrete"><flag ipc="enable"/></option>

<!-- a wire that stays bent -->
<joint type="hinge" stiffness="2" springyield="0.5"/>

<!-- clay that stays dented -->
<elasticity young="9e4" poisson="0" yield="0.003"/>

Joint & tendon plasticity (wire.xml)	3D solid plasticity (clay.xml)
Shell bending plasticity (paper.xml)	Shell plasticity under impact (foil.xml)

Try it: clay, wire, paper, foil, drawstring bag, cable.

Pillar 3: Rebuilt Collisions & Speculative Contacts (<flag speculative="enable"/>)

Across the 3.x releases we rebuilt the collision stack: nativeccd replaced libccd, and single-shot multicontact (multiccd) has expanded to all geom types (including with margin), resulting in a ~4x speedup and significant robustness improvements over multicontact with libccd. The entire collision stack (geoms, SDFs, and flexes) is now fully multithreaded, large-mesh convex collisions got 2x faster, the box-box collider was rewritten, and new contact features include per-contact surface velocity for conveyors and adhesion for magnets and suction. Right: box meshes in single precision with libccd (left) and nativeccd (right).

In 4.0 this culminates in speculative contacts, which prevent thin or fast-moving objects from tunneling through other objects. Speculative contacts sweep fast-moving geoms ahead of time (costing almost nothing for slow ones), keep bodies on the separated side, and generate up to four contact points so thin cards and plates land flat, all without sub-stepping.

In our tests, a robot arm catches a 0.7 mm playing card falling at over 2 m/s every time with a 16 ms timestep, where discrete collision detection misses it at anything above 8 ms. Humanoid stair climbing and thin-object grasping run 6 to 9 times faster, because they can use larger timesteps. In 4.0, speculative contacts cover convex primitives and meshes on CPU; heightfields, SDFs, flexes, MJX and MuJoCo Warp will follow.

<option timestep="0.016"><flag speculative="enable"/></option>

Newton's cradle (3 mm plates, 4 ms)	Chain (thin links, 6 ms)	Baseball & bat (1.2 cm bat, 10 ms)

Click a title to run it in your browser; turn off speculative to watch the objects pass through each other.

Upgrading from 3.x

Most models load unchanged. The changes most likely to affect you are below; the 4.0.0 release notes have the full list and migration recipes.

• Python packages: run pip uninstall -y mujoco before installing 4.0 (see Getting Started).
• Studio: mujoco.experimental.studio is now mujoco.studio; the default viewer plugin is mujoco.studio.app.App.
• Soft bodies: <composite>, the mujoco.elasticity cable and shell plugins, and flexvert equalities are removed in favor of <flexcomp> and continuum <elasticity>. 1D rods need integrator="discrete", Euler or RK4.
• Python 3.10 is no longer supported.

Thank You to Our Community

MuJoCo 4.0 would not exist without the bugs reported, designs debated, and code contributed by our open-source community and ecosystem partners—including our collaborators at NVIDIA and Disney Research on mujoco_warp and Newton, and everyone who contributed across mujoco, mujoco_warp, and mujoco_menagerie since 3.0:

Tell us what you are building, share scenes via live.mujoco.org, and ask questions in the thread below!

— The Google DeepMind Robotics Simulation Team