Metadata-Version: 2.5
Name: playground
Version: 1.0.0
Summary: Playground of robotics real and sim tasks.
Project-URL: Documentation, https://reaf-sim.readthedocs.io/en/latest/playground/index.html
Project-URL: Repository, https://github.com/google-deepmind/mujoco_playground
Project-URL: Issues, https://github.com/google-deepmind/mujoco_playground/issues
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.12
Requires-Dist: absl-py
Requires-Dist: gdm-robotics
Requires-Dist: mujoco-warp>=4.0.0
Requires-Dist: mujoco[sysid]>=4.0.0
Requires-Dist: reaf-sim>=1.0.0
Requires-Dist: reaf>=1.1.2
Requires-Dist: torch<2.14,>=2.7.0
Requires-Dist: warp-lang<1.18.1,>=1.18.0
Provides-Extra: feetech
Requires-Dist: lerobot[feetech]<0.7,>=0.6.0; extra == 'feetech'
Requires-Dist: rerun-sdk; extra == 'feetech'
Requires-Dist: safari-sdk>=2.144.0; extra == 'feetech'
Provides-Extra: i2rt
Requires-Dist: gs-usb==0.3.1; (sys_platform == 'darwin') and extra == 'i2rt'
Requires-Dist: i2rt; extra == 'i2rt'
Requires-Dist: python-can==4.5.0; extra == 'i2rt'
Requires-Dist: pyusb<2,>=1.3.1; (sys_platform == 'darwin') and extra == 'i2rt'
Requires-Dist: rerun-sdk; extra == 'i2rt'
Requires-Dist: safari-sdk>=2.144.0; extra == 'i2rt'
Provides-Extra: identify
Requires-Dist: opencv-python-headless; extra == 'identify'
Requires-Dist: pyserial; extra == 'identify'
Requires-Dist: rerun-sdk; extra == 'identify'
Requires-Dist: safari-sdk>=2.144.0; extra == 'identify'
Provides-Extra: real
Requires-Dist: rerun-sdk; extra == 'real'
Requires-Dist: safari-sdk>=2.144.0; extra == 'real'
Provides-Extra: rl
Requires-Dist: rsl-rl-lib==5.4.2; extra == 'rl'
Requires-Dist: tensorboard; extra == 'rl'
Requires-Dist: tensorboardx; extra == 'rl'
Requires-Dist: tensordict; extra == 'rl'
Provides-Extra: so101
Requires-Dist: lerobot[feetech]<0.7,>=0.6.0; extra == 'so101'
Requires-Dist: opencv-python-headless; extra == 'so101'
Requires-Dist: pyserial; extra == 'so101'
Requires-Dist: rerun-sdk; extra == 'so101'
Requires-Dist: safari-sdk>=2.144.0; extra == 'so101'
Provides-Extra: yam
Requires-Dist: gs-usb==0.3.1; (sys_platform == 'darwin') and extra == 'yam'
Requires-Dist: i2rt; extra == 'yam'
Requires-Dist: opencv-python-headless; extra == 'yam'
Requires-Dist: pyserial; extra == 'yam'
Requires-Dist: python-can==4.5.0; extra == 'yam'
Requires-Dist: pyusb<2,>=1.3.1; (sys_platform == 'darwin') and extra == 'yam'
Requires-Dist: rerun-sdk; extra == 'yam'
Requires-Dist: safari-sdk>=2.144.0; extra == 'yam'
Description-Content-Type: text/markdown

# MuJoCo Playground

[![Build](https://img.shields.io/github/actions/workflow/status/google-deepmind/mujoco_playground/ci.yml?branch=main)](https://github.com/google-deepmind/mujoco_playground/actions)
[![PyPI version](https://img.shields.io/pypi/v/playground)](https://pypi.org/project/playground/)
[![Documentation Status](https://readthedocs.org/projects/reaf-sim/badge/?version=latest)](https://reaf-sim.readthedocs.io/en/latest/playground/index.html)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
![Banner for playground](https://www.gstatic.com/reaf-sim/banner/0/banner.png)

MuJoCo Playground is a suite of robot environments, reinforcement learning tasks, and hardware workflows written in [PyTorch](https://pytorch.org/) and built on [`reaf-sim`](https://github.com/google-deepmind/reaf-sim), [MuJoCo](https://github.com/google-deepmind/mujoco), and [MuJoCo Warp](https://github.com/google-deepmind/mujoco_warp).

Robots exist in [`mujoco_playground/robots/`](mujoco_playground/robots), either in simulation or paired with a hardware counterpart, enabling end-to-end workflows across simulation and hardware:

- **[Large-batch RL training on GPU](mujoco_playground/rl/rsl_rl)**: with state and vision observations across control, manipulation, and humanoid whole-body tracking.
- **[Sim & real teleoperation](mujoco_playground/tasks/teleop/so101)**: with leader-follower control and episodic MCAP logging.
- **[System identification](mujoco_playground/tasks/sysid)**: fitting simulated joint dynamics to logged hardware trajectories via `mujoco.sysid`.
- **[Zero-shot sim-to-real policy deployment](mujoco_playground/tasks/manipulation/pick_cube/so101/deploy)**: running the same task layer and policy in simulation (`--mode=sim`) and on hardware (`--mode=real`).
- **[Agentic manipulation](mujoco_playground/tasks/agentic/tabletop_v0)**: for vision-language model (VLM) examples across simulation and hardware (`SO-101`, `i2rt YAM`).

<table>
  <tr>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/whole_body/tracking"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/g1_lafan_dance/0/g1_lafan_dance.webp" alt="Whole body motion tracking"></a>
      <br><b><a href="mujoco_playground/tasks/whole_body/tracking">Whole body motion tracking</a></b>
    </td>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/teleop/so101"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/so101_sim_teleop/0/so101_sim_teleop.webp" alt="SO-101 Simulation Teleoperation Demo"></a>
      <br><b><a href="mujoco_playground/tasks/teleop/so101">Sim teleoperation</a></b>
    </td>
  </tr>
  <tr>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/teleop/so101"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/so101_real_teleop/0/so101_real_teleop.webp" alt="SO-101 Real Teleoperation Demo"></a>
      <br><b><a href="mujoco_playground/tasks/teleop/so101">Real teleoperation</a></b>
    </td>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/sysid/so101"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/so101_sysid/0/so101_sysid.webp" alt="SO-101 System Identification Rollout"></a>
      <br><b><a href="mujoco_playground/tasks/sysid/so101">System identification</a></b>
    </td>
  </tr>
  <tr>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/manipulation/pick_cube/so101/deploy"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/so101_pick_cube_sim2real/1/so101_pick_cube_sim2real.webp" alt="Sim2Real and interactive viewer"></a>
      <br><b><a href="mujoco_playground/tasks/manipulation/pick_cube/so101/deploy">Sim2Real and interactive viewer</a></b>
    </td>
    <td align="center" width="50%">
      <a href="mujoco_playground/tasks/agentic/tabletop_v0"><img width="420" src="https://www.gstatic.com/reaf-sim/demos/yam_mug_real/0/yam_mug_real.webp" alt="YAM Agentic Tabletop Manipulation"></a>
      <br><b><a href="mujoco_playground/tasks/agentic/tabletop_v0">Agentic manipulation</a></b>
    </td>
  </tr>
</table>

> [!NOTE]
> Looking for the original RSS 2025 JAX/MJX environments? They remain available under [`rss2025`](rss2025).

## Installation

Clone the repository and sync dependencies with [`uv`](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/google-deepmind/mujoco_playground.git && cd mujoco_playground

# Then install with one of:
make sync  # For GPU, good for RL training

make sync-cu12  # For CUDA 12 on Linux

make sync-cpu  # Or for CPU only, (i.e. on macOS)
```

Verify your installation by running the test suite:

```bash
make test
```

> [!NOTE]
> Real-robot hardware SDKs are optional extras so simulation-only stays lightweight. Passing `--extra so101` or `--extra yam` to `uv run` (or `uv sync --extra so101`) installs the hardware drivers on demand.

## Getting Started

To get started, either try training an RL policy, or try agentic manipulation in simulation or on the real hardware.

### Train & Visualize an RL Policy

Train a PPO policy across parallel GPU environments with [RSL-RL](https://github.com/leggedrobotics/rsl_rl):

```bash
# Train SO-101 Pick-Cube
uv run --extra rl python -m mujoco_playground.rl.rsl_rl.train \
  --env=SO101PickCubeVision \
  --logdir=/tmp/rslrl_logs/so101_pick_cube_vision
  #  --overrides='{"nworld": 64}'  # For CPU

# Play back the trained policy in the interactive viewer
uv run --extra rl python -m mujoco_playground.rl.rsl_rl.play \
  --env=SO101PickCubeVision \
  --resume_path=/tmp/rslrl_logs/so101_pick_cube_vision
```

Monitor training curves in TensorBoard:

```bash
uv run --extra rl tensorboard --logdir=/tmp/rslrl_logs/so101_pick_cube_vision
```

Optionally [set up the SO-101 hardware](mujoco_playground/robots/so101/real) and [deploy to the real arm](mujoco_playground/tasks/manipulation/pick_cube/so101/deploy):

```bash
# Deploy the trained policy on the physical SO-101 follower arm
uv run --extra so101 --extra rl python -m \
  mujoco_playground.tasks.manipulation.pick_cube.so101.deploy.run \
  --mode=real \
  --checkpoint=/tmp/rslrl_logs/so101_pick_cube_vision
```

### Try Agentic Manipulation

Spin up the [agentic tabletop manipulation task](mujoco_playground/tasks/agentic/tabletop_v0) directly from your coding agent with a prompt in `sim` or `real`:

```text
Start the tabletop_v0 bridge for the yam in sim and get it to <your task>,
following mujoco_playground/tasks/agentic/tabletop_v0/AGENT_PROMPT.md
```

Swap `sim` for `real` to run on hardware, or `so101` for `yam` (see [`AGENT_PROMPT.md`](mujoco_playground/tasks/agentic/tabletop_v0/AGENT_PROMPT.md)).

> [!NOTE]
> On macOS, `--viewer` requires `mjpython` in place of `python`. Before the
> first run, link `libpython` into the virtualenv so `mjpython` can load it:
>
> ```bash
> ln -sf "$(uv run python -c 'import sys; print(sys.base_prefix)')"/lib/libpython3.13.dylib .venv/lib/
> ```

## Documentation & Contributing

- **Documentation:** See the [MuJoCo Playground documentation](https://reaf-sim.readthedocs.io/en/latest/playground/index.html).
- **Contributing:** See the [contributing guide](https://reaf-sim.readthedocs.io/en/latest/playground/contributing.html) for contribution guidelines.
- **Changelog:** See the [changelog](https://reaf-sim.readthedocs.io/en/latest/playground/changelog.html).

## Citation

If you use MuJoCo Playground in your work, please cite it as follows (see the [GitHub contributors page](https://github.com/google-deepmind/mujoco_playground/graphs/contributors?from=10%2F12%2F2026) for the full list of contributors):

```bibtex
@software{mujoco_playground_2026,
  author = {Tabanpour, Baruch and Howell, Taylor and Haves, Sam and Abeyruwan, Saminda and Ma, Tony and Suh, Dan and {MuJoCo Playground Contributors}},
  title = {{MuJoCo Playground}},
  url = {https://github.com/google-deepmind/mujoco_playground},
  year = {2026},
}
```

For the RSS 2025 benchmark suite that was built on JAX/MJX (see [`rss2025`](rss2025)), please cite:

```bibtex
@misc{mujoco_playground_2025,
  title = {MuJoCo Playground: An open-source framework for GPU-accelerated robot learning and sim-to-real transfer.},
  author = {Zakka, Kevin and Tabanpour, Baruch and Liao, Qiayuan and Haiderbhai, Mustafa and Holt, Samuel and Luo, Jing Yuan and Allshire, Arthur and Frey, Erik and Sreenath, Koushil and Kahrs, Lueder A. and Sferrazza, Carlo and Tassa, Yuval and Abbeel, Pieter},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/google-deepmind/mujoco_playground}
}
```

## License & Disclaimer

All content in this repository is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

This is not an officially supported Google product.
