MuJoCo·LeRobot 설치, 어떤 버전으로 맞춰야 할까: OS별 공식 요구사항과 GPU 없을 때 대안

로봇 시뮬레이션과 모방학습을 처음 시작할 때 가장 먼저 막히는 곳은 모델이 아니라 설치입니다. MuJoCo와 LeRobot은 요구하는 Python 버전이 다르고, PyTorch의 CUDA 빌드와 그래픽 드라이버, 렌더링 백엔드까지 맞물려 있어서 한 군데만 어긋나도 import 단계에서 멈춥니다. 이 글은 2026년 10월 22일 기준 공식 문서와 PyPI 릴리스 정보만으로 두 패키지를 한 가상환경에 설치하는 순서를 정리합니다. 읽고 나면 자신의 OS와 GPU에서 어떤 조합을 골라야 하는지, 설치 후 무엇으로 확인하는지 판단할 수 있습니다.

시뮬레이터를 아직 고르지 않았다면 MuJoCo·Isaac Lab·PyBullet·Genesis 비교를 먼저 보고 오는 편이 좋습니다.

두 패키지가 요구하는 버전부터 맞춘다

PyPI의 mujoco 페이지를 보면 최신 릴리스는 2026년 10월 14일에 올라온 3.16.0이고, Requires-Python은 3.10 이상입니다. PyPI의 lerobot 페이지의 최신 릴리스는 2026년 8월 3일의 0.6.1이며 Python 3.12 이상을 요구하고, 의존성으로 torch>=2.7,<2.12를 지정합니다. 두 조건을 동시에 만족하는 가장 낮은 버전이 3.12이므로 이 글은 Python 3.12를 기준으로 합니다.

이 표는 각 패키지의 릴리스 파일 목록과 LeRobot 설치 문서의 플랫폼 안내를 옮긴 것입니다. MuJoCo 휠에는 MuJoCo 라이브러리가 함께 들어 있어서, MuJoCo Python 문서대로 pip install mujoco 한 줄이면 별도 바이너리를 내려받지 않아도 됩니다. 반대로 3.16.0의 macOS 휠은 arm64용뿐이라 Intel Mac에서는 소스 빌드가 필요해집니다.

Linux에서 CUDA 드라이버와 torch 빌드 맞추기

GPU 학습을 할 계획이라면 설치 전에 nvidia-smi로 드라이버 버전을 확인합니다. LeRobot 설치 문서에 따르면 Linux에서 PyPI 기본 torch 휠은 CUDA 13.0 기반이고 드라이버 하한이 580.65입니다. 드라이버가 그보다 낮으면 lerobot보다 torch를 먼저, 인덱스를 지정해 설치해야 합니다.

macOS와 Windows는 PyPI 기본 휠(각각 MPS, CUDA-Windows 빌드)을 그대로 쓰므로 이 단계를 건너뜁니다.

설치 순서: 가상환경부터 확인 스크립트까지

아래 순서는 conda(miniforge)를 기준으로 합니다. LeRobot 문서가 권장하는 방식이고, ffmpeg를 conda-forge에서 받을 수 있어 PyTorch 버전과 관계없이 동작합니다.

1. Python 3.12 가상환경을 만들고 활성화합니다.
2. Linux NVIDIA 환경이면 드라이버에 맞는 인덱스로 torch를 먼저 설치합니다.
3. TorchCodec 지원 플랫폼이면 conda-forge에서 ffmpeg를 설치합니다. Intel Mac, Linux ARM은 pyav로 자동 대체되므로 생략해도 됩니다.
4. LeRobot을 필요한 extra와 함께 설치하고, MuJoCo를 설치합니다.
5. 확인 스크립트로 세 패키지와 가속기 상태를 한 번에 점검합니다.

conda create -y -n physai python=3.12
conda activate physai

# (Linux + NVIDIA, 드라이버 580.65 미만일 때만) torch를 먼저 지정 설치
pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision

conda install ffmpeg -c conda-forge
pip install 'lerobot[training]' mujoco

WSL 안에 설치한다면 문서 안내대로 conda install evdev -c conda-forge를 추가합니다. lerobot 기본 패키지는 의도적으로 가볍게 구성돼 있어서, 녹화·캘리브레이션은 core_scripts, 학습은 training, SmolVLA는 smolvla, Pi0 계열은 pi extra를 따로 붙여야 합니다.

설치가 끝나면 다음 스크립트를 check_env.py로 저장해 실행합니다.

from importlib.metadata import version

import mujoco
import torch

xml = """
<mujoco>
  <worldbody>
    <body pos="0 0 1">
      <freejoint/>
      <geom type="box" size=".05 .05 .05"/>
    </body>
  </worldbody>
</mujoco>
"""
m = mujoco.MjModel.from_xml_string(xml)
d = mujoco.MjData(m)
for _ in range(200):
    mujoco.mj_step(m, d)

print("mujoco", mujoco.__version__, "box z:", round(float(d.qpos[2]), 3))
print("lerobot", version("lerobot"))
print("torch", torch.__version__,
      "cuda:", torch.cuda.is_available(),
      "mps:", torch.backends.mps.is_available())

상자의 높이 z가 시작값 1보다 작게 나오면 중력이 적용돼 물리 스텝이 돈 것입니다. cuda와 mps 중 자신의 장비에 해당하는 값이 True인지 확인합니다.

화면 없는 서버에서 렌더링 백엔드 고르기

MuJoCo의 OpenGL 렌더링은 세 가지 백엔드 중 하나로 동작합니다. dm_control README는 기본 시도 순서를 GLFW → EGL → OSMesa로 설명하고, MUJOCO_GL 환경 변수로 하나를 고정할 수 있다고 안내합니다.

GPU가 여러 장이면 MUJOCO_EGL_DEVICE_ID로 렌더링에 쓸 GPU를 고릅니다. 백엔드가 제대로 잡혔는지는 MuJoCo Python 문서가 오프스크린 렌더링용으로 설명하는 mujoco.GLContext를 만들어 보면 바로 알 수 있습니다.

export MUJOCO_GL=egl
python -c "import mujoco; ctx = mujoco.GLContext(640, 480); ctx.make_current(); print('GL context OK')"

반대로 로컬 macOS에서 대화형 뷰어를 쓸 때는 다른 문제가 생깁니다. 문서에 따르면 mujoco.viewer.launch_passive는 macOS에서 mjpython 런처로 실행해야 하며, mjpython은 mujoco 패키지에 함께 설치됩니다. python my_script.py 대신 mjpython my_script.py로 실행하면 됩니다.

GPU가 없을 때 선택지와 한계

GPU가 없어도 설치와 시뮬레이션 자체는 가능합니다. MuJoCo 물리 계산은 CPU에서 돌고, 위의 확인 스크립트도 GPU 없이 끝납니다. 막히는 지점은 정책 학습입니다.

Colab FAQ는 무료 버전 노트북이 최대 12시간까지 실행될 수 있지만 가용성과 사용 패턴에 따라 달라지고, 사용 한도는 변동하며 공개하지 않는다고 밝힙니다. 그래서 Colab에서 학습할 때는 체크포인트를 자주 Hugging Face Hub나 Drive에 저장해 세션이 끊겨도 이어서 학습할 수 있게 해 둡니다. LeRobot은 ACT와 SmolVLA의 Colab 학습 노트북 링크를 각 문서에서 제공합니다.

학습에 GPU 메모리가 얼마나 필요한지는 모델마다 크게 다릅니다. SmolVLA 기준 계산은 SmolVLA 파인튜닝 VRAM 계산법에서 따로 다룹니다.

환경을 다시 만들 수 있게 고정해 두는 방법

설치가 한 번 성공하면 버전을 파일로 남겨 두는 것이 다음 문제를 막는 가장 싼 방법입니다. 아래 environment.yml은 이 글의 기준 버전을 고정한 예시입니다.

name: physai
channels:
  - conda-forge
dependencies:
  - python=3.12
  - ffmpeg
  - pip
  - pip:
      - mujoco==3.16.0
      - lerobot[training]==0.6.1

Linux에서 torch 인덱스를 따로 지정했다면 conda env create -f environment.yml 전에 같은 인덱스로 torch를 먼저 설치하는 단계를 README에 함께 적어 둡니다. 실제로 설치된 전체 목록은 pip freeze > requirements.lock.txt로 저장하면 동료 장비에서 같은 조합을 재현할 수 있습니다.

설치가 안 될 때 증상별로 먼저 볼 곳

설치가 끝났다면 LeRobot으로 SO-101 데이터 수집과 ACT 학습으로 바로 넘어가 데이터 파이프라인을 확인할 수 있습니다. 데이터 양에 따라 어떤 정책 모델로 시작할지는 ACT·Diffusion Policy·VLA 선택 기준에서 이어집니다.