설치

이 가이드는 conda(miniforge를 통해)를 사용하여 환경을 관리합니다(권장). 다른 환경 관리자(예: uv, venv)를 선호하는 경우, Python >=3.12가 설치되어 있는지 확인한 후 Environment Setup으로 건너뛰세요.

1단계 (conda 전용): miniforge 설치

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

2단계: 환경 설정

Python 3.12로 가상 환경을 생성합니다:

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

그런 다음 가상 환경을 활성화합니다. lerobot을 사용하려면 셸을 열 때마다 이 작업을 수행해야 합니다.

conda activate lerobot

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

플랫폼 요구 사항

Apple Silicon에서는 PyTorch가 macOS 14 이상을 요구하며, MPS 가속은 macOS 15 이상이 필요합니다(macOS 14에서는 LeRobot이 CPU로 폴백됩니다). Linux에서는 기본 PyTorch wheels가 580.65 이상의 NVIDIA 드라이버를 요구합니다. 구형 드라이버의 경우 PyTorch CUDA variant를 참조하세요.

ffmpeg 설치 (비디오 디코딩용)

LeRobot은 기본적으로 TorchCodec을 비디오 디코딩에 사용하며, 이를 위해 ffmpeg가 필요합니다.

플랫폼 지원: TorchCodec은 macOS Intel (x86_64) 또는 Linux armv7l에서 사용할 수 없습니다. 이러한 플랫폼에서는 LeRobot이 자동으로 pyav로 폴백되므로 ffmpeg를 설치할 필요가 없으며 3단계로 건너뛰면 됩니다.

Jetson (aarch64 + CUDA): 기본적으로 비디오 디코딩은 CPU에서 실행됩니다. docker/Dockerfile.jetson은 JetPack 6.2용 CUDA 지원이 포함된 torch/torchcodec를 소스에서 빌드합니다. 커뮤니티에서 유지 관리되며, 사전 빌드된 이미지는 ravediamond/lerobot-jetson에서, 배경 정보는 이슈 #819에서 확인하세요.

플랫폼이 TorchCodec을 지원하는 경우, 아래 방법 중 하나를 사용하여 ffmpeg를 설치하세요:

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

3단계: LeRobot 설치 🤗

기본 lerobot 설치에는 의도적으로 경량 구성으로, 핵심 ML 의존성(PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors)만 포함됩니다. 더 무거운 의존성은 선택적 추가 항목으로 분리되어 있어 필요한 것만 설치할 수 있습니다.

소스에서

먼저 저장소를 클론한 후 해당 디렉터리로 이동합니다:

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

그런 다음, 라이브러리를 편집 가능 모드에서 설치합니다. 이는 코드에 기여할 계획이 있는 경우 유용합니다.

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)

PyPI에서 설치

핵심 라이브러리: 다음으로 기본 패키지를 설치합니다:

pip install lerobot

uv pip install lerobot

이 명령은 핵심 ML 의존성만 설치합니다. 대부분의 워크플로우에는 추가 항목을 설치해야 합니다.

추가 기능: LeRobot은 일반적인 워크플로에 매핑되는 기능별 추가 기능을 제공합니다. uv를 사용하는 경우, 아래 명령에서 pip install를 uv pip install로 교체하세요.

Composite Extras는 일반적인 CLI 스크립트를 위한 기능 extras를 결합합니다:

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

정책, 환경 및 하드웨어 추가 항목은 여전히 특정 의존성에 사용할 수 있습니다:

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

여러 extras를 결합할 수 있습니다(예: .[core_scripts,pi,pusht]). 사용 가능한 extras의 전체 목록은 pyproject.toml을 참조하세요.

PyTorch CUDA 변형 (Linux 전용)

Linux에서는 torch와 torchvision가 PyPI에서 제공되며, 기본 wheels는 CUDA 13 빌드(최소 드라이버 버전 580.65)입니다. macOS와 Windows 설치에서는 PyPI 기본 wheels를 사용하므로 이 섹션을 건너뛸 수 있습니다.

구형 드라이버 또는 GPU를 사용하는 경우, 먼저 해당 PyTorch index에서 PyTorch를 설치한 후 LeRobot을 설치하세요. PyPI의 Linux TorchCodec도 CUDA 13 빌드이므로 CPU index에서 가져와야 합니다. (torch 버전이 2.11 미만인 경우, TorchCodec compatibility table에서 일치하는 릴리스를 선택하세요):

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는 CUDA 12만 지원하는 드라이버를 위해 PyTorch가 유지하는 빌드입니다. torch 2.15에는 CUDA 12 빌드가 없으므로 이 인덱스는 torch 2.14를 설치합니다. CUDA 12를 유지하는 것은 torch 2.14 또는 이전 버전을 유지하는 것을 의미합니다.

uv pip를 사용하면 --torch-backend로 한 단계에서 인덱스를 선택할 수 있습니다. 예를 들어 uv pip install --torch-backend cu126 lerobot입니다. uv sync는 항상 커밋된 lock을 설치합니다. 여기서 CUDA 빌드를 변경하려면 pyproject.toml의 [tool.uv.index]와 [tool.uv.sources]에 인덱스를 추가하고 uv lock을 다시 실행하세요.

문제 해결

빌드 오류가 발생하면 추가 시스템 종속성을 설치해야 할 수 있습니다: cmake, build-essential, ffmpeg libs. Linux에서 이들을 설치하려면 다음을 실행하세요:

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

다른 시스템의 경우: PyAV 컴파일

선택적 종속성

LeRobot은 특정 기능에 대한 선택적 추가 항목(extras)을 제공합니다. 여러 추가 항목을 조합할 수 있습니다(예: .[aloha,feetech]). 사용 가능한 모든 추가 항목은 pyproject.toml을 참조하세요. uv를 사용하는 경우, 아래 명령에서 pip install을 uv pip install로 교체하세요.

시뮬레이션

환경 패키지를 설치합니다: aloha (gym-aloha), pusht (gym-pusht), libero (Linux 전용) 또는 metaworld. 이들은 dataset extra를 자동으로 포함합니다.

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

모터 제어

모터에 맞는 추가 항목을 설치하세요: Koch v1.1은 dynamixel, SO100/SO101/Moss는 feetech입니다. 두 항목 모두 rustypot를 통해 모터와 통신합니다.

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

실험 추적

Trackio는 training extra에 포함되어 있습니다. 로컬 실행에는 계정이나 로그인이 필요하지 않으며, ~/.cache/huggingface/trackio 아래에 있는 로컬 SQLite 데이터베이스에 저장됩니다. 다음 명령으로 대시보드를 열 수 있습니다:

trackio show --project lerobot

Hugging Face Space(없으면 생성됨)에 실행을 동기화하려면 hf auth login을 실행하고 --trackio.space_id=<user>/<space>를 전달하세요. 트래킹이 활성화된 원격 작업(--job.target)은 작업이 종료되면 pod의 로컬 데이터베이스가 손실되므로 space_id가 필요합니다.

Space의 프라이버시 기본값은 None입니다. 조직의 기본값이 private가 아닌 한, 새로 생성되는 Space는 public입니다. private Space를 생성하려면 --trackio.private=true를 전달하세요.

각 실행(run)은 해당 실행을 시작하는 명령어와 콘솔 출력(print, 로그, traceback)을 기록하며, 이 둘은 모두 대시보드의 실행 페이지에 표시됩니다. Space에서는 Space 자체와 동일한 가시성을 가지며, --trackio.capture_console=false를 전달하면 콘솔 출력을 실행에서 제외할 수 있습니다.

Weights & Biases에서 마이그레이션

다음 단계

• 로봇이 있으신가요? 사이드바의 Robots 섹션에서 해당 로봇 페이지(예: SO-101)를 참고하여 조립 및 보정을 수행한 후, imitation learning tutorial을 따라 데이터셋을 기록하고 첫 번째 정책을 학습해 보세요.
• 아직 하드웨어가 없으신가요? LIBERO에서 시뮬레이션으로 정책을 학습하고 평가하거나, Colab 노트북을 사용해 보세요.
• 기여하고 싶으신가요? 기여 가이드를 읽어보세요.
• 치트 시트를 손에 두세요. 모든 LeRobot 명령어를 한곳에 정리해 두었습니다.