google-deepmind/mujoco_menagerie

google-deepmind/mujoco_menagerie

Description: A collection of high-quality models for the MuJoCo physics engine, curated by Google DeepMind.

Language: Python

License: NOASSERTION

Stars: 3596

Forks: 490

Open issues: 49

Created: 2022-09-05T10:37:53Z

Pushed: 2026-06-04T21:14:46Z

Default branch: main

Fork: no

Archived: no

README:

Menagerie is a collection of high-quality models for the MuJoCo physics engine, curated by Google DeepMind.

A physics simulator is only as good as the model it is simulating, and in a powerful simulator like MuJoCo with many modeling options, it is easy to create "bad" models which do not behave as expected. The goal of this collection is to provide the community with a curated library of well-designed models that work well right out of the gate.

• [Getting Started](#getting-started)
• [Prerequisites](#prerequisites)
• [Overview](#overview)
• [Usage](#usage)
• [Via robot-descriptions](#via-robot-descriptions)
• [Via git clone](#via-git-clone)
• [Model Quality and Contributing](#model-quality-and-contributing)
• [Quick contributor setup](#quick-contributor-setup)
• [Menagerie Models](#menagerie-models)
• [Citing Menagerie](#citing-menagerie)
• [Acknowledgments](#acknowledgments)
• [Changelog](#changelog)
• [License and Disclaimer](#license-and-disclaimer)

Getting Started

Prerequisites

The minimum required MuJoCo version for each model is specified in its respective README. You can download prebuilt binaries for MuJoCo from the GitHub releases page, or if you are working with Python, you can install the native bindings from PyPI via pip install mujoco. For alternative installation instructions, see here.

Overview

The structure of Menagerie is illustrated below. For brevity, we have only included one model directory since all others follow the exact same pattern.

├── unitree_go2
│   ├── assets
│   │   ├── base_0.obj
│   │   ├── ...
│   ├── go2.png
│   ├── go2.xml
│   ├── LICENSE
│   ├── README.md
│   └── scene.xml
│   └── go2_mjx.xml
│   └── scene_mjx.xml

• assets: stores the 3D meshes (.stl or .obj) of the model used for visual and

collision purposes

• LICENSE: describes the copyright and licensing terms of the model
• README.md: contains detailed steps describing how the model's MJCF XML file

was generated

• .xml: contains the MJCF definition of the model
• scene.xml: includes .xml with a plane, a light source and

potentially other objects

• .png: a PNG image of scene.xml
• _mjx.xml: contains an MJX-compatible version of the model. Not all

models have an MJX variant.

• scene_mjx.xml: same as scene.xml but loads the MJX variant

Note that .xml solely describes the model, i.e., no other entity is defined in the kinematic tree. We leave additional body definitions for the scene.xml file, as can be seen in the Shadow Hand [scene.xml](shadow_hand/scene_right.xml).

Usage

Via robot-descriptions

You can use the opensource `robot_descriptions` package to load any model in Menagerie. It is available on PyPI and can be installed via pip install robot_descriptions.

Once installed, you can load a model of your choice as follows:

import mujoco

# Loading a specific model description as an imported module.
from robot_descriptions import panda_mj_description
model = mujoco.MjModel.from_xml_path(panda_mj_description.MJCF_PATH)

# Directly loading an instance of MjModel.
from robot_descriptions.loaders.mujoco import load_robot_description
model = load_robot_description("panda_mj_description")

# Loading a variant of the model, e.g. panda without a gripper.
model = load_robot_description("panda_mj_description", variant="panda_nohand")

Via git clone

You can also directly clone this repository in the directory of your choice:

git clone https://github.com/google-deepmind/mujoco_menagerie.git

You can then interactively explore the model using the Python viewer:

python -m mujoco.viewer --mjcf mujoco_menagerie/unitree_go2/scene.xml

If you have further questions, please check out our [FAQ](FAQ.md).

Model Quality and Contributing

Our goal is to eventually make all Menagerie models as faithful as possible to the real system they are being modeled after. Improving model quality is an ongoing effort, and the current state of many models is not necessarily as good as it could be.

However, by releasing Menagerie in its current state, we hope to consolidate and increase visibility for community contributions. To help Menagerie users set proper expectations around the quality of each model, we introduce the following grading system:

| Grade | Description | |-------|-------------------------------------------------------------| | A+ | Values are the product of proper system identification | | A | Values are realistic, but have not been properly identified | | B | Stable, but some values are unrealistic | | C | Conditionally stable, can be significantly improved |

The grading system will be applied to each model once a proper system identification toolbox is created. We are currently planning to release this toolbox later this year.

For more information regarding contributions, for example to add a new model to Menagerie, see [CONTRIBUTING](CONTRIBUTING.md).

Quick contributor setup

Two commands and you're set up. You need `uv` installed; that's the only prerequisite.

make install # one-time: installs pre-commit + git hook
make all # run every check CI runs (lint + format + license + XML + tests)

After make install, the fast checks fire automatically on every git commit. Run make all before pushing. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full breakdown.

Menagerie Models

> Click any thumbnail below to open the model in an in-browser MuJoCo viewer powered by live.mujoco.org.

Humanoids.

| Preview | Name | DoFs | License | |:---:|---|---|---| | | Unitree H1 | 19 | [BSD-3-Clause](unitree_h1/LICENSE) | | | Robotis OP3 | 20 | [Apache-2.0](robotis_op3/LICENSE) | | | Unitree G1 | 29 | [BSD-3-Clause](unitree_g1/LICENSE) | | | TALOS | 44 | [Apache-2.0](pal_talos/LICENSE) | | | Booster T1 |…