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에 게시합니다. 각 이미지는 Docker 게시 워크플로를 통해 연결된 Dockerfile에서 빌드됩니다.

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를 제외합니다.

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 네임스페이스 공유를 활성화하며, 프로세스 간 메모리 공유에 필수적입니다. --device nvidia.com/gpu=... 플래그는 CDI를 통해 컨테이너가 호스트의 GPU에 액세스할 수 있도록 합니다.

파일 접근성에 대한 참고 사항#

컨테이너 내에서 로컬 컴퓨터의 파일을 사용하려면 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 사용#

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

yolo predict model=yolo26n.pt show=True

Docker GUI 사용을 마친 후#

xhost -local:docker

이제 Docker에서 Ultralytics를 사용할 수 있도록 설정되었으며 그 기능을 활용할 준비가 되었습니다. Ultralytics 웹 애플리케이션을 셀프 호스팅하려면 Platform On-Premise 가이드를 참조하세요. 다른 Python 패키지 설치 방법은 Ultralytics 빠른 시작 문서를 참조하세요.

FAQ#