Ultralytics Docker 빠른 시작 가이드#

이 가이드는 Ultralytics 프로젝트용 Docker 환경을 설정하는 방법을 포괄적으로 소개합니다. Docker는 애플리케이션을 컨테이너에서 개발, 배포 및 실행하는 플랫폼입니다. 배포 위치와 관계없이 소프트웨어가 항상 동일하게 실행되도록 하는 데 특히 유용합니다. 자세한 내용은 Docker Hub의 Ultralytics Docker 저장소를 참조하세요.

이 가이드에서 배울 내용#

• NVIDIA 지원을 사용해 Docker 설정하기
• Ultralytics Docker 이미지 설치하기
• CPU 또는 GPU 지원을 사용해 Docker 컨테이너에서 Ultralytics 실행하기
• Docker에서 디스플레이 서버를 사용해 Ultralytics 탐지 결과 표시하기
• 컨테이너에 로컬 디렉터리 마운트하기

사전 요구 사항#

• 시스템에 Docker가 설치되어 있는지 확인하세요. 설치되어 있지 않다면 Docker 웹사이트에서 다운로드하여 설치할 수 있습니다.
• GPU 가속을 사용하려면 시스템에 NVIDIA GPU와 NVIDIA 드라이버가 설치되어 있는지 확인하세요. CPU 이미지는 NVIDIA 하드웨어가 필요하지 않습니다.
• NVIDIA Jetson 장치를 사용하는 경우 적절한 JetPack 버전이 설치되어 있는지 확인하세요. 자세한 내용은 NVIDIA Jetson 가이드를 참조하세요.

NVIDIA 지원을 사용해 Docker 설정하기(선택 사항)#

먼저 다음 명령어를 실행하여 NVIDIA 드라이버가 올바르게 설치되었는지 확인합니다.

nvidia-smi

NVIDIA Container Toolkit 설치#

이제 Docker 컨테이너에서 GPU 지원을 활성화하기 위해 NVIDIA Container Toolkit을 설치합니다.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit

Docker에서 CDI 장치 확인#

GPU CDI 장치를 사용할 수 있는지 확인하려면 nvidia-ctk cdi list을 실행합니다(toolkit의 nvidia-cdi-refresh 서비스는 toolkit >= 1.18에서 사양을 자동으로 생성하고 유지 관리합니다).

nvidia-ctk cdi list

nvidia.com/gpu=0 및 nvidia.com/gpu=all과 같은 항목이 표시되어야 합니다. 검색된 CDI 장치는 docker info에도 표시됩니다.

Ultralytics Docker 이미지 설치#

Ultralytics는 다음 이미지를 Docker Hub에 게시합니다. 각 이미지는 연결된 Dockerfile을 사용해 Docker 게시 워크플로에서 빌드됩니다.

AMD64 GPU 이미지(latest, latest-export 및 latest-runner)는 PyTorch 2.14 및 CUDA 13.2를 사용합니다. 이미지를 실행하기 전에 nvidia-smi으로 호스트 드라이버의 CUDA 지원을 확인하세요. 새 컨테이너를 설치해도 호스트 드라이버는 업그레이드되지 않습니다. CUDA 13에서는 Tesla P100 및 V100을 포함한 Maxwell, Pascal 및 Volta GPU 지원이 제거되었습니다. NVIDIA CUDA 릴리스 노트와 드라이버 호환성 요구 사항을 참조하세요.

NVIDIA ARM64 이미지는 CUDA 13.4 및 TensorRT 11.2와 함께 NVIDIA PyTorch 26.08을 사용합니다. Thor에서 지원되는 PyTorch가 TensorRT까지 지원되는 것은 아닙니다. NVIDIA는 JetPack에서 TensorRT 11.2를 지원하지 않습니다. Jetson TensorRT 내보내기에는 사용 중인 JetPack 릴리스에서 지원되는 TensorRT 10.x 런타임을 사용하세요. Jetson 가이드 또는 DGX Spark 가이드의 플랫폼 요구 사항을 따르세요. JetPack 4, 5 및 6 이미지는 각 장치 전용 스택을 별도로 유지합니다.

Conda Dockerfile은 로컬 빌드에 사용할 수 있습니다. latest-conda의 자동 게시가 비활성화되어 있으므로 해당 레지스트리 태그에는 이 업데이트가 포함되지 않습니다.

LiteRT 내보내기에는 latest-python-export을 사용하세요. GPU latest-export 이미지는 PyTorch 2.14를 유지하며, 현재 종속성이 PyTorch 2.14 미만을 요구하므로 LiteRT를 포함하지 않습니다.

Python, CPU, Jupyter 및 CPU runner 이미지는 Python 3.14를 사용합니다. Python 내보내기 이미지는 latest-python-3.13 베이스를 사용하며, TensorFlow, CoreML 및 PaddlePaddle이 아직 Python 3.14를 지원하지 않으므로 --build-arg PYTHON_VERSION=3.13를 포함한 동일한 Dockerfile-python에서 빌드됩니다.

latest으로 시작하는 태그는 가장 최근에 게시된 main 브랜치 빌드를 가리킵니다. 버전 지정 태그는 latest 접두사를 VERSION, VERSION-cpu 또는 VERSION-jetson-jetpack6와 같은 Ultralytics 릴리스로 대체합니다. 재현 가능한 환경을 위해 버전 지정 태그를 사용하세요.

최신 이미지를 가져오려면 다음을 실행합니다.

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

대신 직접 이미지를 빌드하려면 저장소를 복제한 다음, 빌드 컨텍스트로 저장소 루트를 사용하고 위 표에서 해당하는 Dockerfile을 지정합니다.

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Docker 컨테이너에서 Ultralytics 실행#

Ultralytics Docker 컨테이너를 실행하는 방법은 다음과 같습니다.

CPU만 사용#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

GPU 사용#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

-it 플래그는 pseudo-TTY를 할당하고 stdin을 열린 상태로 유지하여 컨테이너와 상호 작용할 수 있게 합니다. --ipc=host 플래그는 호스트의 IPC 네임스페이스 공유를 활성화하며, 프로세스 간 메모리 공유에 필수적입니다. NVIDIA GPU의 경우 --device nvidia.com/gpu=... 플래그를 사용하면 CDI를 통해 액세스할 수 있습니다. AMD GPU의 경우 --device 플래그를 사용하면 GPU 커널 드라이버(/dev/kfd)와 디스플레이 렌더 노드(/dev/dri)에 액세스할 수 있습니다.

파일 액세스 관련 참고 사항#

컨테이너 내에서 로컬 컴퓨터의 파일을 사용하려면 Docker 볼륨을 사용할 수 있습니다.

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

/path/on/host을 로컬 컴퓨터의 디렉터리 경로로 바꾸고, /path/in/container을 Docker 컨테이너 내부에서 사용할 경로로 바꾸세요.

학습 출력 유지#

학습 출력은 기본적으로 컨테이너 내 /ultralytics/runs/<task>/<name>/에 저장됩니다. 호스트 디렉터리를 마운트하지 않으면 컨테이너를 제거할 때 출력이 손실됩니다.

학습 출력을 유지하려면 다음을 실행합니다.

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

이 명령은 모든 학습 출력을 호스트 컴퓨터의 ./runs에 저장합니다.

Docker 컨테이너에서 그래픽 사용자 인터페이스(GUI) 애플리케이션 실행#

Docker는 주로 백그라운드 애플리케이션과 CLI 프로그램을 컨테이너화하는 데 사용되지만, 그래픽 프로그램도 실행할 수 있습니다. Linux 환경에서는 그래픽 디스플레이를 처리하는 두 가지 주요 그래픽 서버인 X11(X Window System이라고도 함)과 Wayland이 사용됩니다. 시작하기 전에 현재 사용 중인 그래픽 서버를 확인해야 합니다. 확인하려면 다음 명령을 실행하세요:

env | grep -E -i 'x11|xorg|wayland'

X11 또는 Wayland 디스플레이 서버의 설정 및 구성은 이 가이드의 범위에 포함되지 않습니다. 위 명령을 실행해도 아무것도 표시되지 않으면 계속 진행하기 전에 먼저 시스템에서 둘 중 하나를 사용할 수 있도록 설정해야 합니다.

GUI를 사용하여 Docker 컨테이너 실행하기#

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

GUI에서 Docker 사용하기#

Ultralytics 이미지에는 headless OpenCV가 포함되어 있으므로, 먼저 컨테이너 내부에 OpenCV GUI 빌드와 시스템 라이브러리를 설치합니다:

apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-python

이제 Docker 컨테이너 내에서 그래픽 애플리케이션을 표시할 수 있습니다. 예를 들어, 다음 CLI 명령을 실행하여 YOLO26 모델의 예측 결과를 시각화할 수 있습니다:

yolo predict model=yolo26n.pt show=True

Docker GUI 사용을 마친 후#

xhost -local:docker

이제 Docker에서 Ultralytics를 사용할 준비가 완료되었으며, 다양한 기능을 활용할 수 있습니다. Ultralytics 웹 애플리케이션을 자체 호스팅하려면 플랫폼 온프레미스 가이드를 참조하세요. Python 패키지를 설치하는 다른 방법은 Ultralytics 빠른 시작 문서를 참조하세요.

자주 묻는 질문#