# 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](#step-2-environment-setup).

## Etapa 1 (apenas `conda`): Instale o [`miniforge`](https://conda-forge.org/download/)

```bash
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:

```bash
conda create -y -n lerobot python=3.12
```

= apenas 2.10)>
```bash
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:

```bash
conda activate lerobot
```

> [!NOTE]
> Ao instalar o LeRobot dentro do WSL (Windows Subsystem for Linux), certifique-se de também instalar o `evdev`:
>
> ```bash
> conda install evdev -c conda-forge
> ```

= apenas 2.10)>
```bash
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\activate
```

> [!NOTE]
> Ao instalar o LeRobot dentro do WSL (Windows Subsystem for Linux), certifique-se de também instalar o `evdev`:
>
> ```bash
> sudo apt install libevdev-dev
> uv pip install evdev
> ```

### 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](#pytorch-cuda-variant-linux-only).

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

LeRobot usa [TorchCodec](https://github.com/meta-pytorch/torchcodec) para decodificação de vídeo por padrão, o que requer `ffmpeg`.

> [!NOTE]
> **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`](https://github.com/huggingface/lerobot/blob/main/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`](https://github.com/ravediamond/lerobot-jetson) para a imagem pré-compilada e a issue [#819](https://github.com/huggingface/lerobot/issues/819) para mais contexto.

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

Instale o `ffmpeg` no seu ambiente conda. Isso funciona com **todos os versões do PyTorch** e é **obrigatório para PyTorch < 2.10**:

```bash
conda install ffmpeg -c conda-forge
```

> [!TIP]
> Isso geralmente instala o `ffmpeg 8.X` com o codificador `libsvtav1`. Se você encontrar problemas (por exemplo, `libsvtav1` ausente — verifique com `ffmpeg -encoders` — ou uma incompatibilidade de versão com o `torchcodec`), você pode instalar explicitamente o `ffmpeg 7.1.1` usando:
>
> ```bash
> conda install ffmpeg=7.1.1 -c conda-forge
> ```

= apenas 2.10)>

A partir do **PyTorch >= 2.10** (TorchCodec ≥ 0.10), o TorchCodec pode fazer link dinamicamente para uma instalação de `ffmpeg` em todo o sistema. Isso é útil ao usar `uv` ou outros gerenciadores de ambiente que não sejam `conda`:

```bash
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg
```

> [!IMPORTANT]
> O `ffmpeg` do sistema é **suportado apenas com PyTorch >= 2.10** (TorchCodec ≥ 0.10). Para versões anteriores do PyTorch, você **deve** usar `conda install ffmpeg -c conda-forge` em vez disso.

## 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:

```bash
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.

```bash
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)
```

```bash
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:

```bash
pip install lerobot
```

```bash
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.

| Extra      | O que ele adiciona                                | Caso de uso típico                    |
| ---------- | ------------------------------------------- | ----------------------------------- |
| `dataset`  | `datasets`, `av`, `torchcodec`, `jsonlines` | Carregando e criando conjuntos de dados         |
| `training` | `dataset` + `accelerate`, `trackio`         | Políticas de treinamento                   |
| `hardware` | `pynput`, `pyserial`, `deepdiff`            | Conectando a robôs reais           |
| `viz`      | `rerun-sdk`, `foxglove-sdk`                 | Visualização durante a gravação/avaliação |

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

| Extra          | Inclui                       | Caso de uso típico                                        |
| -------------- | ------------------------------ | ------------------------------------------------------- |
| `core_scripts` | `dataset` + `hardware` + `viz` | `lerobot-record`, `lerobot-replay`, `lerobot-calibrate` |
| `evaluation`   | `av`                           | `lerobot-eval` (adicione extras de política e ambiente conforme necessário)      |
| `dataset_viz`  | `dataset` + `viz`              | `lerobot-dataset-viz`, `lerobot-imgtransform-viz`       |

```bash
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:

```bash
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](https://pytorch.org/get-started/locally/) 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](https://github.com/meta-pytorch/torchcodec#installing-torchcodec)):

```bash
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
```

> [!NOTE]
> `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 instalar esses pacotes no Linux, execute:

```bash
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](https://pyav.org/docs/develop/overview/installation.html#bring-your-own-ffmpeg)

## 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](https://github.com/huggingface/gym-aloha)), `pusht` ([gym-pusht](https://github.com/huggingface/gym-pusht)), [`libero`](./libero) (somente Linux) ou [`metaworld`](./metaworld). Esses pacotes incluem automaticamente o extra `dataset`.

```bash
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](https://github.com/pollen-robotics/rustypot).

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

### Rastreamento de Experimentos

[Trackio](https://huggingface.co/docs/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:

```bash
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

| Configuração do W&B                     | Configuração do Trackio                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `--wandb.enable=true`           | `--trackio.enable=true`                                                                          |
| `--wandb.project=<project>`     | `--trackio.project=<project>`                                                                    |
| `--wandb.disable_artifact=true` | Já é o padrão; use `--trackio.disable_artifact=false` para ativar                            |
| `--wandb.entity=<team>`         | Escolha `--trackio.space_id=<user-or-org>/<space>` para logging hospedado                             |
| `--wandb.run_id=<id>`           | Use `--trackio.run_name=<name>` para uma execução existente do **Trackio**                                  |
| `--wandb.mode=offline`          | Omita `space_id` para registro local; também desdefina `TRACKIO_SPACE_ID` e `TRACKIO_SERVER_URL` se estiverem definidos |
| `--wandb.mode=disabled`         | `--trackio.enable=false`                                                                         |
| `--wandb.console=off`           | `--trackio.capture_console=false`                                                                |

## Próximas etapas

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