LeRobot 개발 환경 구축하기

개발 환경은 실습의 안전망이다

LeRobot을 잘 쓰려면 먼저 개발 환경을 안정적으로 만들어야 한다. 로봇 학습은 코드만 실행하는 일이 아니다. Python 패키지, PyTorch, GPU 드라이버, 카메라, USB 포트, Hugging Face Hub 인증이 함께 맞아야 한다. 이 중 하나가 어긋나면 데이터 수집이나 학습 이전 단계에서 시간을 잃는다.

LeRobot은 현실 세계 로보틱스를 위한 PyTorch 기반 도구다. 모델, 데이터셋, 학습 스크립트, 평가 도구, 실제 로봇 제어 인터페이스를 함께 제공한다.¹ 따라서 이번 장의 목표는 "설치가 되었다"에서 끝나지 않는다. 앞으로 데이터셋을 내려받고, 정책을 학습하고, 필요하면 실제 로봇까지 연결할 수 있는 기본 작업대를 만드는 것이 목표다.

이 장에서는 가장 무난한 기준으로 conda 가상환경 + Git 설치 + PyTorch 확인 + Hub 로그인 흐름을 사용한다. 단순히 LeRobot을 체험만 할 경우에는 PyPI에서 바로 설치할 수도 있다. 하지만 이 책은 이후 데이터 수집, 정책 학습, 로봇 연결까지 다루므로 Git 저장소를 받아 editable 모드로 설치하는 방식도 함께 설명한다.

AI 생성 이미지

기본 도구 준비하기

먼저 필요한 도구를 확인하자.

• Python: LeRobot과 PyTorch 실행에 필요하다.

• conda 또는 Miniforge: 프로젝트별 가상환경을 만들기 위해 사용한다.

• Git: LeRobot 저장소를 내려받고 업데이트하기 위해 필요하다.

• ffmpeg: 비디오 디코딩·인코딩에 필요할 수 있다.

• PyTorch: 정책 학습과 추론의 핵심 딥러닝 프레임워크다.

• CUDA 드라이버: NVIDIA GPU로 학습할 때 필요하다.

가상환경을 쓰는 이유는 단순하다. 로봇 프로젝트는 의존성이 많다. 한 환경에 ROS, OpenCV, PyTorch, 여러 로봇 SDK를 섞으면 패키지 충돌이 자주 난다. LeRobot 전용 환경을 따로 만들면 문제가 생겼을 때 삭제하고 다시 만들기 쉽다.

공식 설치 문서는 현재 Python 3.12 이상을 기준으로 안내한다.³ 예전 튜토리얼이나 특정 하드웨어 글에서 Python 3.10을 볼 수 있지만, 새 프로젝트를 시작한다면 설치한 LeRobot 버전의 공식 문서와 pyproject.toml 요구사항을 먼저 확인해야 한다. 이 책에서는 최신 공식 문서 흐름에 맞춰 Python 3.12 환경을 기준으로 설명한다.

conda create -y -n lerobot python=3.12
conda activate lerobot
python --version

프롬프트 앞에 (lerobot)이 보이면 현재 터미널은 LeRobot 전용 환경 안에 있다. 앞으로 설치 명령은 이 환경을 활성화한 상태에서 실행한다.

비디오 처리를 위해 ffmpeg도 준비한다. LeRobot은 플랫폼과 PyTorch 버전에 따라 TorchCodec 또는 PyAV를 사용할 수 있는데, conda 환경에 ffmpeg를 설치해 두면 비디오가 포함된 데이터셋을 다룰 때 문제가 줄어든다.³

conda install -y ffmpeg -c conda-forge
ffmpeg -version

PyTorch와 GPU 확인하기

LeRobot은 PyTorch 위에서 동작한다. PyTorch는 CPU만으로도 설치할 수 있고, NVIDIA GPU가 있다면 CUDA 버전을 설치해 학습 속도를 크게 높일 수 있다. PyTorch 공식 설치 페이지는 운영체제, 패키지 관리자, Python, CUDA 버전에 맞는 설치 명령을 선택하도록 안내한다.²

가장 중요한 기준은 이것이다.

• 데이터셋 구조 확인, 코드 실습, 소규모 테스트: CPU도 가능하다.

• 이미지 기반 정책 학습, 큰 데이터셋 학습, 반복 실험: GPU가 사실상 필요하다.

• 실제 로봇 제어와 데이터 수집: GPU보다 USB, 카메라, 지연시간 설정이 더 중요할 때가 많다.

GPU가 있는 Linux나 Windows 환경에서는 먼저 드라이버가 보이는지 확인한다.

nvidia-smi

명령이 정상 출력되면 NVIDIA 드라이버는 인식되고 있다. 그다음 PyTorch를 설치한다. 정확한 명령은 CUDA 버전에 따라 달라지므로 PyTorch 공식 설치 선택기를 따르는 것이 가장 안전하다. 설치 후에는 다음 코드로 확인한다.

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU only')"

torch.cuda.is_available()가 True이면 PyTorch가 GPU를 사용할 수 있다. False라고 해서 LeRobot 설치가 실패한 것은 아니다. CPU 모드로도 많은 준비 작업은 가능하다. 다만 학습 시간이 길어진다. 예를 들어 GPU에서는 몇 시간 안에 끝날 실험이 CPU에서는 훨씬 오래 걸릴 수 있다. 그래서 처음에는 CPU로 설치 확인을 끝내고, 실제 학습 단계에서 GPU 서버나 클라우드 환경을 붙이는 방식도 현실적이다.

CUDA 문제가 날 때는 보통 세 가지 중 하나다.

1. NVIDIA 드라이버가 설치되지 않았거나 오래되었다.

2. CPU 전용 PyTorch를 설치했다.

3. WSL2나 Docker 안에서 GPU가 전달되지 않았다.

이때는 LeRobot을 다시 설치하기보다 PyTorch부터 확인해야 한다. LeRobot의 학습 속도 문제처럼 보이지만 실제 원인은 PyTorch와 드라이버 조합인 경우가 많다.

LeRobot 설치하기

LeRobot은 PyPI에서 바로 설치할 수 있다.³

pip install lerobot
lerobot-info

가볍게 둘러보는 목적이라면 이것으로 충분하다. 하지만 책의 실습처럼 예제 코드를 읽고, 하드웨어 옵션을 설치하고, 필요하면 코드를 수정하려면 Git 저장소를 내려받는 방식이 좋다.

cd ~
git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -U pip
pip install -e .

-e는 editable 설치를 뜻한다. 저장소의 코드를 수정하면 다시 설치하지 않아도 현재 환경에 반영된다. 실제 로봇, 특히 SO-ARM 계열처럼 Feetech 서보를 쓰는 장비를 다룰 계획이라면 관련 옵션을 함께 설치한다.³

pip install -e ".[feetech]"

시뮬레이션 환경이나 특정 정책을 사용할 때는 별도 extra가 필요할 수 있다. 예를 들어 ALOHA, PushT, Feetech 모터 제어처럼 기능별 의존성이 나뉘어 있으므로, 공식 문서와 lerobot-train --help를 기준으로 필요한 것만 추가한다.

설치가 끝나면 먼저 정보 명령을 실행한다.

lerobot-info

명령이 없다면 현재 환경이 맞는지 확인한다.

which python
which pip
pip show lerobot

Windows PowerShell에서는 which 대신 다음을 쓸 수 있다.

where python
where pip

설치 확인은 복잡한 학습부터 시작하지 말고, 가벼운 import 테스트부터 한다.

python -c "import lerobot; print('LeRobot import OK')"
python -c "from lerobot.datasets import LeRobotDataset; print('Dataset API OK')"

여기까지 통과하면 Python 환경과 LeRobot 기본 패키지는 정상이다.

예제 명령으로 동작 확인하기

LeRobot은 명령행 도구를 제공한다. 공식 README와 문서에서 자주 만나는 기본 명령은 다음 계열이다.³

lerobot-info
lerobot-train
lerobot-eval
lerobot-record
lerobot-rollout

처음 설치 확인 단계에서 바로 긴 학습을 돌릴 필요는 없다. 데이터셋 다운로드와 학습이 함께 일어나므로 시간이 걸릴 수 있다. 먼저 도움말이 뜨는지 확인한다.

lerobot-train --help
lerobot-eval --help
lerobot-record --help

도움말이 출력되면 CLI 등록은 정상이다. 인터넷 연결과 Hub 접근까지 확인하고 싶다면 작은 공개 데이터셋을 읽는 테스트를 진행할 수 있다. 단, 데이터셋 크기에 따라 다운로드 시간이 걸릴 수 있으므로 처음에는 import 테스트만으로 충분하다.

실제 로봇을 연결할 계획이라면 포트와 카메라 탐색 도구를 미리 확인한다. LeRobot은 버전별로 CLI가 정리되는 중이므로, 하나의 블로그 명령을 그대로 외우기보다 현재 설치본의 문서와 --help를 우선한다. 절차는 항상 같다.

포트 확인 → 모터 설정 → 캘리브레이션 → 텔레오퍼레이션 → 데이터 기록

SO-ARM 계열 로봇을 준비하는 경우에는 모터 설정, 캘리브레이션, 텔레오퍼레이션 명령을 사용하게 된다. 예를 들어 포트가 /dev/ttyACM0이면 다음과 같은 형태가 된다.⁴

lerobot-setup-motors \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0

명령 이름이나 옵션은 LeRobot 버전에 따라 달라질 수 있다. 따라서 실습 전에는 반드시 공식 문서와 lerobot-setup-motors --help처럼 현재 설치된 명령의 도움말을 확인한다.

Hugging Face Hub 연동 준비하기

LeRobot은 Hugging Face Hub와 강하게 연결되어 있다. 사전학습 모델과 로봇 데이터셋이 Hub에 올라가고, 사용자는 자신의 데이터셋과 학습한 정책도 Hub에 올릴 수 있다.¹ 로컬에서만 실험할 수도 있지만, 장기적으로는 Hub 계정을 준비하는 편이 좋다.

먼저 Hugging Face 계정을 만든다. 그다음 Settings에서 Access Token을 생성한다. 공개 데이터셋을 내려받기만 한다면 read 토큰이면 충분하다. 데이터셋이나 모델을 업로드하려면 write 권한이 필요하다. Hugging Face Hub 문서도 저장소 생성이나 업로드에는 write 권한 토큰이 필요하다고 설명한다.⁵

CLI 로그인을 위해 huggingface_hub를 설치하거나 업데이트한다.

pip install -U huggingface_hub
hf auth login

프롬프트가 나오면 토큰을 붙여 넣는다. 로그인 확인은 다음 명령으로 한다.

hf auth whoami

구버전 문서나 예제에서는 다음 명령을 볼 수도 있다.

huggingface-cli login

최근 문서에서는 hf auth login을 권장하지만, 둘 중 하나로 인증이 되면 된다. 토큰은 코드에 직접 적지 않는다. 노트북이나 GitHub에 토큰이 올라가면 다른 사람이 내 계정으로 저장소를 만들거나 파일을 올릴 수 있다. 서버나 노트북 환경에서는 환경변수 HF_TOKEN을 쓰는 방식도 가능하다.

데이터 기록 실습에서는 업로드 여부를 명확히 지정해야 한다. 아직 Hub 설정을 하지 않았다면 로컬 저장을 선택한다.

--dataset.push_to_hub=false

옵션 이름은 LeRobot 버전에 따라 바뀔 수 있다. 중요한 원칙은 같다. Hub에 올릴 준비가 되지 않았다면 push 옵션을 끄고, 업로드할 때는 사용자이름/데이터셋이름 형식의 repo id를 쓴다.

Windows, WSL2, Linux에서 주의할 점

Linux는 로봇 개발에 가장 무난하다. USB 장치가 /dev/ttyACM0, /dev/ttyUSB0 같은 이름으로 잡히고, 권한만 맞추면 바로 접근할 수 있다. 포트 권한 오류가 나면 현재 사용자를 dialout 그룹에 추가한다.

sudo usermod -aG dialout $USER

그다음 로그아웃 후 다시 로그인하거나 재부팅한다. 그룹 권한은 새 세션부터 적용되는 경우가 많다.

Windows에서 WSL2를 쓰는 경우에는 한 단계가 더 필요하다. 로봇 제어 보드는 Windows에 연결되지만, LeRobot은 WSL2 안에서 실행되기 때문이다. 이때 usbipd-win으로 USB 장치를 WSL2에 전달한다.⁴

Windows PowerShell에서 장치를 확인한다.

usbipd list

처음 한 번 공유한다.

usbipd bind --busid <X-Y>

WSL2로 연결한다.

usbipd attach --wsl --busid <X-Y>

WSL2 터미널에서는 다음처럼 확인한다.

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
dmesg | tail -20

macOS에서는 포트 이름이 /dev/tty.usbmodem... 형태로 보일 수 있다. 카메라를 처음 사용할 때는 개인정보 보호 설정에서 터미널이나 Python 실행 환경에 카메라 권한을 허용해야 한다.

자주 발생하는 문제와 해결법

가장 흔한 문제는 패키지 충돌이다. 해결 원칙은 단순하다. base 환경에 설치하지 말고, LeRobot 전용 환경을 새로 만든다. 문제가 꼬였으면 오래 붙잡지 말고 환경을 다시 만드는 편이 빠르다.

conda deactivate
conda env remove -n lerobot
conda create -y -n lerobot python=3.12
conda activate lerobot

설치 후 충돌 여부는 다음으로 확인한다.

pip check

No broken requirements found가 나오면 좋다. 충돌 메시지가 나오면 어떤 패키지가 어떤 버전을 요구하는지 확인한다.

두 번째는 serial 모듈 오류다. 포트 탐색이나 모터 연결 중 다음과 비슷한 오류가 날 수 있다.

ModuleNotFoundError: No module named 'serial'

이때는 pyserial을 설치한다.

pip install pyserial

세 번째는 ffmpeg 또는 비디오 디코딩 오류다. 데이터셋에 비디오가 포함되어 있는데 ffmpeg와 디코더 조합이 맞지 않으면 저장이나 디코딩에서 실패한다. conda 환경 안에서 다시 설치한다.

conda install -y ffmpeg -c conda-forge

네 번째는 ROS2와 Python 버전 충돌이다. 예를 들어 ROS2 Humble의 rclpy는 Ubuntu 22.04의 system Python 3.10에 맞춰 설치되는 경우가 많다. 반면 최신 LeRobot 환경은 Python 3.12 이상을 요구한다. 이 둘을 한 Python 프로세스에 억지로 넣으면 ABI, 즉 Python 바이너리 호환성 문제에 부딪힐 수 있다. 이럴 때는 한 환경에 합치려 하지 말고, LeRobot 프로세스와 ROS2 프로세스를 분리한 뒤 ZeroMQ 같은 IPC로 통신시키는 구조가 안전하다.⁶

다섯 번째는 CUDA 인식 문제다. nvidia-smi는 되는데 torch.cuda.is_available()가 False이면 PyTorch 설치가 CPU 버전일 가능성이 크다. 반대로 nvidia-smi 자체가 안 되면 드라이버나 WSL GPU 설정부터 고쳐야 한다.

마지막으로 권한 문제다. Linux에서 /dev/ttyACM0 접근이 거부되면 dialout 그룹을 확인한다. Windows에서는 PowerShell을 관리자 권한으로 열어야 하는 경우가 있다. macOS에서는 보안 설정과 USB 케이블 품질도 확인한다. 충전 전용 케이블은 데이터 통신이 되지 않는다.

설치 완료 체크리스트

다음 항목을 통과하면 다음 장으로 넘어갈 준비가 된 것이다.

conda activate lerobot
python --version
ffmpeg -version
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import lerobot; print('LeRobot OK')"
lerobot-info
hf auth whoami

실제 로봇을 연결할 예정이라면 추가로 확인한다.

lerobot-record --help
lerobot-rollout --help

처음부터 완벽한 GPU 서버와 로봇 장비가 없어도 괜찮다. 중요한 것은 환경을 분리하고, 작은 명령부터 확인하며, 문제가 생겼을 때 어느 층에서 발생했는지 나누어 보는 습관이다. Python 문제인지, PyTorch 문제인지, LeRobot 문제인지, USB 권한 문제인지 분리해서 보면 대부분의 설치 오류는 해결할 수 있다.

다음 장에서는 이렇게 설치한 LeRobot 저장소 안으로 들어가 프로젝트 구조를 살펴본다. 어떤 코드가 데이터셋을 다루고, 어떤 코드가 정책을 학습하며, 어떤 부분이 로봇 하드웨어와 연결되는지 차례대로 확인할 것이다.

참고

¹LeRobot Hugging Face 커뮤니티 페이지

²PyTorch Get Started Locally

³Hugging Face LeRobot 설치 문서

⁴UnrealRobotics: SO-101 개발 환경 및 USB 연결 메모

⁵Hugging Face Hub Quickstart

⁶UnrealRobotics: SO-101 ROS2와 LeRobot 환경 분리 사례