pip Install vs Source Install

Choose the install method that matches your situation:

pip install

Use this if you are following this path on a supported robot or in simulation without modifying LeRobot internals. Fastest and most stable.

Source install

Use this if you need to add a custom hardware config for an unsupported robot, or if you want to contribute back to LeRobot. Requires cloning the repo.

pip install (recommended)

# Create a virtual environment (recommended) python3 -m venv ~/lerobot-env source ~/lerobot-env/bin/activate # Install LeRobot pip install lerobot # Verify the install python -c "import lerobot; print(lerobot.__version__)"

Source install

git clone https://github.com/huggingface/lerobot.git cd lerobot python3 -m venv ~/lerobot-env source ~/lerobot-env/bin/activate # Install in editable mode pip install -e . # Verify python -c "import lerobot; print(lerobot.__version__)"
Python version matters: LeRobot requires Python 3.10 or higher. If python3 --version shows 3.8 or 3.9, install 3.10 via your package manager or pyenv before proceeding.

Hardware Config Setup

LeRobot uses a config file to know which robot you are connecting to. If you are using simulation only, you can skip this section — the simulator uses its own built-in config.

  1. Find your robot's config

    LeRobot ships with configs for all supported hardware in lerobot/configs/robot/. Look for your robot: so100.yaml, koch.yaml, openarm.yaml, dk1.yaml, etc. If your robot is not listed, see the source install path above and check the LeRobot GitHub for a community-contributed config.

  2. Copy and edit the config

    Copy your robot's config to your working directory and edit the serial port to match your system. Run ls /dev/tty* with your robot connected to identify the port (typically /dev/ttyUSB0 or /dev/ttyACM0).

  3. Set your HuggingFace token

    Run huggingface-cli login and paste your HuggingFace token. This is needed for pushing datasets and models in Units 3 and 6. Your token is at huggingface.co/settings/tokens — create one with write access.

Verify with a Simulation Run

Before touching any real hardware, confirm your install is working by running a pre-trained ACT policy in MuJoCo. This downloads a policy checkpoint from HuggingFace Hub and runs it in the gym_pusht environment.

source ~/lerobot-env/bin/activate # Install MuJoCo sim environment pip install lerobot[gym_pusht] # Run the pre-trained ACT policy in simulation python -m lerobot.scripts.eval \ --pretrained-policy-name-or-path lerobot/act_pusht_keypoints \ --env.name gym_pusht/PushT-v0 \ --eval.n-episodes 3 \ --eval.use-async-envs false

You will see a visualization window showing the robot arm attempting to push a T-shaped block into a target position. The policy is pre-trained — your job is just to confirm it runs without errors. A success rate above 0% on 3 episodes is enough to confirm your environment is correctly configured.

No display? If you are on a headless server, add --env.render-mode null to suppress the visualization window and just print success/failure metrics to the terminal.

Common Install Errors

Error Fix
No module named 'lerobot'Your virtual environment is not activated. Run source ~/lerobot-env/bin/activate.
mujoco.FatalErrorMuJoCo requires a display. On headless servers add --env.render-mode null or use Xvfb.
ImportError: libGL.so.1Install OpenGL libraries: sudo apt install libgl1-mesa-glx.
huggingface_hub.errors.RepositoryNotFoundErrorRun huggingface-cli login and paste your token. The policy download requires authentication.

Unit 1 Complete When...

The lerobot.scripts.eval command runs 3 sim episodes and exits without errors. You see policy rollout output (episode reward or success flag) printed to the terminal. Your hardware config file exists and your HuggingFace token is set. You are ready to explore real datasets in Unit 2.