📦 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? 🖥️

New to 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, type cmd or powershell, and press Enter
• macOS: Press Cmd + Space, type Terminal, and press Enter
• Linux: Press Ctrl + Alt + T or search for "Terminal" in your applications

Basic tips:

• Type commands exactly as shown in the instructions
• Press Enter after typing each command to run it
• You can copy and paste commands (right-click to paste in most command line interfaces)

tip

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

Linux / macOS

In your terminal, run:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

In your terminal, run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

tip

We recommend Python 3.12 as it's the latest supported version for Reachy Mini.

📂 Install Git and Git LFS

Linux

Install Git and Git LFS

In your terminal, run:

sudo apt install git git-lfs

macOS

1. Install Homebrew (if not already installed)

In your terminal, run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

For Apple Silicon (M1, M2, etc.), you will also be prompted to run:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Homebrew

Once the installation is completed you can check if it went fine with:

brew --version

2. Install Git and Git LFS

In your terminal, run:

brew install git git-lfs

:::

Windows

Download and install Git for Windows

Download and install Git for Windows: https://git-scm.com/install/windows

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

Linux / macOS

In your terminal, run:

source reachy_mini_env/bin/activate

Windows - First-time setup

Before you can activate your virtual environment, Windows needs permission to run scripts. You only need to do this once!

Step 1: Open terminal as Administrator

• Press Win + R, type powershell
• Right-click on "Windows PowerShell" and select "Run as administrator"

Step 2: Enable script execution

In the administrator terminal, run:

powershell Set-ExecutionPolicy RemoteSigned

Step 3: Close the administrator terminal and open a regular terminal

Now you can activate your virtual environment by running:

reachy_mini_env\Scripts\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.0

If 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.0

note

The 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.0

If 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.

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 $USER

warning

Log 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.

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.