Instalação

Este guia usa conda (via miniforge) para gerenciar ambientes (recomendado). Se você preferir outro gerenciador de ambientes (por exemplo, uv, venv), verifique se você tem Python >=3.12 e, em seguida, pule para Configuração do Ambiente.

Etapa 1 (apenas conda): Instale o miniforge

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Etapa 2: Configuração do ambiente

Crie um ambiente virtual com Python 3.12:

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

Em seguida, ative seu ambiente virtual; você precisa fazer isso cada vez que abrir um shell para usar o lerobot:

conda activate lerobot

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\activate

Requisitos da plataforma

No Apple Silicon, o PyTorch requer macOS 14 ou mais recente, e a aceleração MPS requer macOS 15 ou mais recente (no macOS 14, o LeRobot usa CPU como alternativa). No Linux, as rodas padrão do PyTorch exigem um driver NVIDIA da versão 580.65 ou mais recente; para drivers mais antigos, consulte PyTorch CUDA variant.

Instale o ffmpeg (para decodificação de vídeo)

LeRobot usa TorchCodec para decodificação de vídeo por padrão, o que requer ffmpeg.

Suporte da plataforma: TorchCodec não está disponível em macOS Intel (x86_64) ou Linux armv7l. Nessas plataformas, o LeRobot faz automaticamente o fallback para pyav — portanto, você não precisa instalar ffmpeg e pode pular para a Etapa 3.

Jetson (aarch64 + CUDA): a decodificação de vídeo é executada na CPU por padrão. docker/Dockerfile.jetson compila torch/torchcodec a partir do código-fonte com suporte a CUDA para o JetPack 6.2 — mantido pela comunidade, veja ravediamond/lerobot-jetson para a imagem pré-compilada e a issue #819 para mais contexto.

Se sua plataforma suporta TorchCodec, instale o ffmpeg usando um dos métodos abaixo:

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

Etapa 3: Instale o LeRobot 🤗

A instalação base do lerobot é intencionalmente leve — ela inclui apenas as dependências de ML essenciais (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). Dependências mais pesadas ficam atrás de extras opcionais, para que você instale apenas o que precisa.

A partir da origem

Primeiro, clone o repositório e navegue até o diretório:

git clone https://github.com/huggingface/lerobot.git
cd lerobot

Em seguida, instale a biblioteca em modo editável. Isso é útil se você planeja contribuir para o código.

pip install -e ".[core_scripts]"  # For robot workflows (recording, replaying, calibrate)
pip install -e ".[training]"      # For training policies
pip install -e ".[all]"           # Everything (all policies, envs, hardware, dev tools)

uv pip install -e ".[core_scripts]"  # For robot workflows (recording, replaying, calibrate)
uv pip install -e ".[training]"      # For training policies
uv pip install -e ".[all]"           # Everything (all policies, envs, hardware, dev tools)

Instalação a partir do PyPI

Biblioteca principal: Instale o pacote base com:

pip install lerobot

uv pip install lerobot

Isso instala apenas as dependências principais de ML. Você precisará adicionar extras para a maioria dos fluxos de trabalho.

Extras de recursos: O LeRobot oferece extras por recurso que correspondem a fluxos de trabalho comuns. Se você estiver usando uv, substitua pip install por uv pip install nos comandos abaixo.

Composite Extras combinam extras de recursos para scripts de CLI comuns:

pip install 'lerobot[core_scripts]'          # Record, replay, calibrate
pip install 'lerobot[training]'              # Train policies
pip install 'lerobot[core_scripts,training]' # Record + train
pip install 'lerobot[all]'                   # Everything

Extras de política, ambiente e hardware ainda estão disponíveis para dependências específicas:

pip install 'lerobot[pi]'             # Pi0/Pi0.5/Pi0-FAST policy deps
pip install 'lerobot[smolvla]'        # SmolVLA policy deps
pip install 'lerobot[diffusion]'      # Diffusion policy deps (diffusers)
pip install 'lerobot[aloha,pusht]'    # Simulation environments
pip install 'lerobot[feetech]'        # Feetech motor support

Vários extras podem ser combinados (por exemplo, .[core_scripts,pi,pusht]). Para a lista completa de extras disponíveis, consulte pyproject.toml.

Variante CUDA do PyTorch (somente Linux)

No Linux, torch e torchvision vêm do PyPI, cujos wheels padrão são builds do CUDA 13 (driver mínimo 580.65). Instalações no macOS e Windows usam os wheels padrão do PyPI e podem pular esta seção.

Para um driver ou GPU mais antigo, instale primeiro o PyTorch a partir do índice do PyTorch correspondente e, em seguida, o LeRobot. O TorchCodec para Linux no PyPI também é uma build CUDA 13, então obtenha-o do índice de CPU (com torch abaixo de 2.11, escolha a release correspondente na tabela de compatibilidade do TorchCodec):

pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision
pip install --index-url https://download.pytorch.org/whl/cpu torchcodec
pip install -e ".[all]"          # source
# — or —
pip install lerobot              # from PyPI

cu126 é a build que o PyTorch mantém para drivers que suportam apenas CUDA 12. O torch 2.15 não possui build para CUDA 12, portanto esse índice instala o torch 2.14, e permanecer no CUDA 12 significa permanecer no torch 2.14 ou em versões anteriores.

Com uv pip, --torch-backend seleciona o índice em uma etapa, por exemplo, uv pip install --torch-backend cu126 lerobot. uv sync sempre instala o lock commitado: para alterar a build do CUDA lá, adicione o índice a [tool.uv.index] e [tool.uv.sources] em pyproject.toml e execute novamente uv lock.

Solução de problemas

Se você encontrar erros de compilação, pode ser necessário instalar dependências de sistema adicionais: cmake, build-essential e ffmpeg libs. Para instalá-los no Linux, execute:

sudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev

Para outros sistemas, consulte: Compilando o PyAV

Dependências opcionais

LeRobot fornece extras opcionais para funcionalidades específicas. Vários extras podem ser combinados (por exemplo, .[aloha,feetech]). Para todos os extras disponíveis, consulte pyproject.toml. Se você estiver usando uv, substitua pip install por uv pip install nos comandos abaixo.

Simulações

Instale os pacotes do ambiente: aloha (gym-aloha), pusht (gym-pusht), libero (somente Linux) ou metaworld. Esses incluem automaticamente o extra dataset.

pip install -e ".[aloha]" # or "[pusht]" for example

Controle de Motor

Instale o extra para seus motores: dynamixel para Koch v1.1, feetech para SO100/SO101/Moss. Ambos se comunicam com os motores através do rustypot.

pip install -e ".[feetech]" # or "[dynamixel]" for example

Rastreamento de Experimentos

Trackio está incluído no extra training. Execuções locais não exigem conta ou login: elas são armazenadas em um banco de dados SQLite local em ~/.cache/huggingface/trackio. Abra o painel com:

trackio show --project lerobot

Para sincronizar execuções com um Hugging Face Space (criado se não existir), execute hf auth login e passe --trackio.space_id=<user>/<space>. Jobs remotos (--job.target) com rastreamento habilitado exigem space_id, pois o banco de dados local do pod é perdido quando o job termina.

A privacidade do Space é definida como None por padrão: novos Spaces são públicos, a menos que o padrão da organização seja privado. Passe --trackio.private=true para criar um Space privado.

Cada execução registra o comando que a iniciou e sua saída de console (prints, logs, tracebacks), ambos exibidos na página da execução no dashboard. Em um Space, eles são tão visíveis quanto o próprio Space; passe --trackio.capture_console=false para manter a saída de console fora da execução.

Migrando do Weights & Biases

Próximas etapas

• Tem um robô? Monte e calibre-o seguindo a página correspondente em Robots na barra lateral (por exemplo, SO-101), depois registre um conjunto de dados e treine sua primeira política com o tutorial de aprendizado por imitação.
• Ainda não tem hardware? Treine e avalie uma política em simulação com LIBERO ou experimente os notebooks do Colab.
• Quer contribuir? Leia o guia de contribuição.
• Mantenha a folha de referência à mão: ela lista todos os comandos do LeRobot em um só lugar.