Reachy Mini documentation
📦 Installation Guide
📦 Installation Guide
Welcome to Reachy Mini! This guide will help you install the Python SDK and daemon to start controlling your robot.
| 🐧 Linux | 🍎 macOS | 🪟 Windows |
|---|---|---|
| ✅ Supported | ✅ Supported | ✅ Supported |
Need help? Feel free to open an issue if you encounter any problem.
First time using the command line? 🖥️
Click here if you're new to using a terminal/command line
A command line (also called terminal or command prompt) is a text-based interface where you can type commands to interact with your computer. Don’t worry—it’s simpler than it looks!
How to open the command line:
- Windows: Press
Win + R, typecmdorpowershell, and press Enter - macOS: Press
Cmd + Space, typeTerminal, and press Enter - Linux: Press
Ctrl + Alt + Tor search for “Terminal” in your applications
Basic tips:
- Type commands exactly as shown in the instructions
- Press
Enterafter typing each command to run it - You can copy and paste commands (right-click to paste in most command line interfaces)
Don’t be intimidated! The command line is just another way to give instructions to your computer. Follow the commands step by step, and you’ll be controlling your Reachy Mini in no time!
1. 📋 Prerequisites
| Tool | Version | Purpose |
|---|---|---|
| 🐍 Python | 3.10 - 3.12 | Run Reachy Mini SDK |
| 📂 Git | Latest | Download source code and apps |
| 📦 Git LFS | Latest | Download model assets |
🐍 Install Python
We’ll use uv - a fast Python package manager that makes installation simple!
Step 1: Install uv
In your terminal, run:
curl -LsSf https://astral.sh/uv/install.sh | sh
✅ Verify installation:
Once the installation is completed, close your terminal and open a new one. You can check if everything went well with :
uv --version
Step 2: Install Python
In your terminal, run:
uv python install 3.12 --default
We recommend Python 3.12 as it’s the latest supported version for Reachy Mini.
📂 Install Git and Git LFS
✅ Finalize installation:
Finally, Git LFS then needs to be initialized with the command :
git lfs install
2. 🏠 Set up a Virtual Environment
Why use a virtual environment? It keeps your Reachy Mini installation isolated and prevents conflicts with other Python projects. Modern Python development requires this!
Create the environment
In your terminal, run:
uv venv reachy_mini_env --python 3.12
Activate the environment
In your terminal, run:
source reachy_mini_env/bin/activate✅ Success indicator: You should see
(reachy_mini_env)at the start of your command line prompt!
3. 🚀 Install Reachy Mini
Choose your installation method:
| 📦 PyPI Installation | 🔧 Source Installation |
|---|---|
| For Everyone | For Developers |
| Ready to use | Modify the code |
📦 Option A: Install from PyPI
Recommended for most users - Just want to control your robot? This is for you!
In your terminal, run:
uv pip install "reachy-mini"
uv pip install --upgrade --index-url https://gitlab.freedesktop.org/api/v4/projects/1340/packages/pypi/simple gstreamer==1.28.0If you want to use the simulation mode, you need to add the mujoco extra:
uv pip install "reachy-mini[mujoco]"
uv pip install --upgrade --index-url https://gitlab.freedesktop.org/api/v4/projects/1340/packages/pypi/simple gstreamer==1.28.0The post installation of gstreamer is due to an issue with PyPi and should be solved in the future.
🔧 Option B: Install from Source
For developers - Want to modify the SDK or contribute? Choose this option!
In your terminal, run:
git clone https://github.com/pollen-robotics/reachy_mini
cd reachy_mini
uv pip install -e .
uv pip install --upgrade --index-url https://gitlab.freedesktop.org/api/v4/projects/1340/packages/pypi/simple gstreamer==1.28.0If you want to use the simulation mode, you need to add the mujoco extra:
uv pip install -e ".[mujoco]"
uv pip install --upgrade --index-url https://gitlab.freedesktop.org/api/v4/projects/1340/packages/pypi/simple gstreamer==1.28.0🐧 Linux Users
Linux + USB connection? You need to grant access to Reachy Mini’s serial port.
🔧 Click here to set up USB permissions
Run these commands in your terminal:
echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="55d3", MODE="0666", GROUP="dialout"
SUBSYSTEM=="usb", ATTRS{idVendor}=="38fb", ATTRS{idProduct}=="1001", MODE="0666", GROUP="dialout"' \
| sudo tee /etc/udev/rules.d/99-reachy-mini.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG dialout $USERLog out and log back in for the changes to take effect!
PortAudio Make sure that portaudio is installed on your system to enable audio features with the default backend.
🔧 Installing PortAudio
Run this command in your terminal:
sudo apt-get install libportaudio2
Gstreamer
Media management is performed by the GStreamer library. Windows and MacOSX users can use pip to install it:
uv pip install --upgrade --index-url https://gitlab.freedesktop.org/api/v4/projects/1340/packages/pypi/simple gstreamer==1.28.0
Linux users have extra steps to follow:
🎉 Congratulations!
You’ve successfully installed Reachy Mini! Your robot is ready to come to life.
❓ Troubleshooting
Encountering an issue? 👉 Check the Troubleshooting & FAQ Guide
Next Steps
- Quickstart Guide: Run your first behavior on Reachy Mini
- 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.