Reachy Mini Simulation - Setup Guide

You don’t need a physical robot to start building! The Reachy Mini simulation runs on MuJoCo and provides a realistic physics environment to prototype, test, and debug your applications.

1. Installation

📋 Prerequisites: Before setting up the simulation, you must first complete the basic installation and virtual environment setup by following the Installation Guide. This guide assumes you already have the Reachy Mini SDK installed and your virtual environment activated.

The simulation requires the mujoco python bindings. You can install them alongside the Reachy Mini software with the extra tag [mujoco].

With pip, run :

pip install "reachy-mini[mujoco]"

With uv, run :

uv pip install "reachy-mini[mujoco]"

2. Running the Simulation

To start the simulated robot, simply run the daemon command with the --sim flag:

reachy-mini-daemon --sim

A window should open displaying the 3D view of the robot. You can interact with the view using your mouse (drag to rotate, right-click to pan, scroll to zoom).

🍎 Mac Users (Apple Silicon / Intel)

On macOS, MuJoCo requires a specific launcher to work correctly with the GUI. Instead of the command above, use mjpython:

mjpython -m reachy_mini.daemon.app.main --sim

⚠️ macOS Users: uv may have compatibility issues with MuJoCo on macOS. If you encounter installation or runtime problems, it’s recommended to use pip directly instead of uv for MuJoCo-related packages.

3. Reachy Mini Control and Apps

You can use Reachy Mini Control to interact with the simulated robot. Simply open the app and connect to the local simulation.

• Apps: You can install and run Apps! They will execute inside the simulation (e.g., the robot will move in the 3D viewer).

4. Scenes & Options

You can customize the simulation environment using the --scene argument.

• empty (default): Just the robot in a void.
• minimal: Adds a table and some objects (apple, croissant, duck) to play with.

Example:

reachy-mini-daemon --sim --scene minimal

5. Connecting your Code

Once the simulation is running, it behaves exactly like a real Reachy Mini Lite connected via USB. The daemon listens on localhost, and you can run any Python SDK script without modification:

from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

# Connects to the simulation running on localhost
with ReachyMini() as mini:
    print("Connected to simulation!")
    
    # Look up and tilt head
    print("Moving head...")
    mini.goto_target(
        head=create_head_pose(z=20, roll=10, mm=True, degrees=True),
        duration=1.0
    )

    # Wiggle antennas
    print("Wiggling antennas...")
    mini.goto_target(antennas=[0.6, -0.6], duration=0.3)
    mini.goto_target(antennas=[-0.6, 0.6], duration=0.3)
    
    # Reset to rest position
    mini.goto_target(
        head=create_head_pose(),
        antennas=[0, 0],
        duration=1.0
    )

Next Steps

• Python SDK: Learn to move, see, speak, and hear.
• AI Integrations: Connect LLMs, build Apps, and publish to Hugging Face.
• Core Concepts: Architecture, coordinate systems, and safety limits.

❓ Troubleshooting

ERROR: Caught a segmentation fault while loading plugin file:
.../gstreamer_python/lib/gstreamer-1.0/libgstpython.dylib

# Find the file inside your environment (adjust the path to match yours)
mv $(python -c "import gstreamer_python, pathlib; print(pathlib.Path(gstreamer_python.__file__).parent / 'lib/gstreamer-1.0/libgstpython.dylib')") \
   $(python -c "import gstreamer_python, pathlib; print(pathlib.Path(gstreamer_python.__file__).parent / 'lib/gstreamer-1.0/libgstpython_.dylib')")

Encountering another issue? 👉 Check the Troubleshooting & FAQ Guide