Docker로 GPU 환경 구성하기

AI 관련 라이브러리나 소프트웨어를 활용하면서 GPU를 다룰 때, 어려움을 겪으신적이 있으신가요? 저는 대부분 Docker 환경에서 GPU를 사용하는 데, 관련 자료가 많이 부족하기도 하고 서버 환경에 따라 오류 해결 방법이 다르기 때문에 어렵게 느껴지는 것 같네요.

그래서 이번 글에서는 Docker로 GPU를 활용하는 환경을 구축하는 방법과 실제 프로젝트 진행 중 겪었던 오류들을 공유하고자 합니다.

해당 글에서 다루고 있는 모든 방법들과 트러블 슈팅 내용들은 다음과 같은 환경에서 진행했습니다.
Host OS: Ubuntu 24.04 LTS
Docker version: 27.1.2
Docker Compose version: 2.29.1
NVIDIA Toolkit version: 1.16.1
NVIDIA Driver Version: 535.171.04
CUDA Version (from NVIDIA-SMI): 12.2

 

Docker 설치부터 GPU 테스트까지

1. Docker 설치

먼저 Docker를 설치해줍니다.

공식 문서에 나와있는 Ubuntu 기준으로 apt repository를 설정하는 명령어를 실행합니다.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

 

docker와 docker compose 모두 사용 가능하도록 docker 관련 패키지들을 설치하는 명령어를 실행해줍시다.

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

 

설치 방법은 Docker 공식 문서를 참고했습니다. Ubuntu가 아닌 다른 OS의 서버에 설치할 때는 명령어가 다를 수 있으니 공식문서를 참고해서 설치해주세요.

 

Install

2. NVIDIA Container Toolkit 설치

Docker 환경에서 GPU를 사용하기 위해 NVIDIA Container Toolkit 설치가 필요합니다 아래 순서를 따라 설치를 진행해주세요.

먼저, 버전에 맞는 NVIDIA repository 주소를 생성하기 위해 현재 사용 중인 리눅스 버전을 distribution 변수에 저장합니다.

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

 

NVIDIA 저장소의 GPG 키를 다운로드합니다.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

 

apt가 NVIDIA Docker 관련 패키지를 인식할 수 있도록 버전에 맞는 NVIDIA Docker repository 리스트 파일을 /etc/apt/sources.list.d/ 경로에 저장합니다.

curl -fsSL 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://#' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

 

다시 한 번 패키지 목록을 갱신하고 nvidia-container-toolkit을 설치합니다.

설치 완료 후, Docker를 재시작해서 변경사항을 적용해줍니다.

sudo apt update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

 

설치 명령어는 해당 공식문서를 참고했습니다.

Installing the NVIDIA Container Toolkit — NVIDIA Container Toolkit

 

처음 Docker를 설치하면 일반적인 Linux 서버 환경에서의 유저는 docker 명령어를 실행할 권한이 없기 때문에, sudo를 명령어 앞에 붙여야 실행 가능할겁니다. sudo 없이 Docker 실행하는 방법은 아래 명령어들을 차례대로 입력해주면 됩니다.

sudo usermod -aG docker $USER
newgrp docker​

docker 그룹에 현재 사용자를 추가하고 재부팅해주면 권한 설정이 적용됩니다. 가끔 바로 적용되지 않을 때가 있는데 저는 일정 시간 동안 기다리니깐 해결됐었습니다.

 

3. 설치 확인 및 GPU 사용 테스트

이때까지 설치한 것들에 대해 제대로 설치가 되었는지 버전을 확인하고 Docker로 GPU 인식 테스트까지 해보겠습니다.

 

Docker 버전을 확인해줍니다. (GPU 기능은 Docker 19.03 버전 이상부터 지원됩니다.)

docker --version

 

Docker Compose 버전을 확인해줍니다. (v2 버전 이상을 권장합니다.)

docker compose version

 

NVIDIA Container Toolkit이 잘 설치되었는지 확인해봅시다.

nvidia-container-cli --version

 

그리고 NVIDIA 런타임이 기본으로 설정되어 있는지 확인해봅시다.

해당 설정이 되어있어야 GPU를 컨테이너에서 기본으로 사용할 수 있습니다.

cat /etc/docker/daemon.json

 

아래처럼 default-runtime: nvidia이 제대로 기재되어 있어야 합니다.

만약 default-runtime이 nvidia가 아니라면 아래 내용을 복붙해주시면 됩니다.

{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}

 

이제 Docker 컨테이너 안에서 GPU가 제대로 인식되는지 테스트 해봅시다.

호스트 OS와 똑같이 nvidia-smi 결과로 GPU 목록이 조회되면 테스트 성공입니다.

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

 

직접 테스트 한 결과입니다.

Sun Mar 30 13:35:34 2025       
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.171.04             Driver Version: 535.171.04   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA GeForce RTX 2080 Ti     Off | 00000000:24:00.0 Off |                  N/A |
| 24%   40C    P2              49W / 250W |   1437MiB / 11264MiB |      1%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+
|   1  NVIDIA GeForce RTX 2080 Ti     Off | 00000000:29:00.0 Off |                  N/A |
| 22%   36C    P2              48W / 250W |   1517MiB / 11264MiB |      0%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

 

이외에도 Docker 컨테이너 내부에서 GPU가 정상적으로 인식되고 있는지 테스트 가능한 방법을 소개드리겠습니다.

docker run -it --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 bash

apt update
apt install -y python3 python3-pip

pip install torch
python3 -c "import torch; print(torch.cuda.is_available())"

 

PyTorch로 테스트 가능하고, True가 출력되면 테스트 성공입니다.

트러블 슈팅 모음

1. /opt/ss: not found

컨테이너 내부에서 nvidia-smi 실행 시, 발생했던 오류였습니다.

해당 경우에는 관련 자료도 많이 없었고, AI한테 물어봐도 답이 안 나와서 꽤 시간이 걸렸던 오류입니다.

여러 가지 해결책을 시도해본 결과 다음과 같이 해결했습니다.

 

1. nvidia-smi 바이너리 내부 문자열을 확인합니다.

strings /usr/bin/nvidia-smi | grep "/opt/ss"

 

 

해당 명령어를 실행했을 때, /opt/ss 문자열이 포함되어 있다면, nvidia-smi 실행 파일 자체가 /opt/ss를 실행하도록 설정된 것입니다.

컨테이너 내부에서도 실행해보고 호스트에서도 실행해보세요. 제 경우에는 호스트에서는 nvidia-smi가 잘 실행되었지만, 컨테이너 내부에서만 작동하지 않았습니다.

 

만약 컨테이너 내부에서만 /opt/ss 문자열이 발견되었다면, 해당 방법으로 호스트 nvidia-smi 실행 파일을 컨테이너로 마운트 해줍니다.

docker run --rm --gpus all \
  -v /usr/bin/nvidia-smi:/usr/bin/nvidia-smi:ro \
  -v /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1:/usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1:ro \
  nvidia/cuda:12.1.0-cudnn8-devel-ubuntu20.04 nvidia-smi

 

만약 호스트에서도 /opt/ss 문자열이 발견되었으면, NVIDIA 드라이버 패키지를 다시 설치해야 합니다. 버전은 현재 nvidia 드라이버 버전에 맞게 설정해주세요.

sudo rm -f /usr/bin/nvidia-smi
sudo apt update
sudo apt install --reinstall nvidia-utils-535

 

마지막으로 /opt/ss 문자열이 남아있는지 최종 점검해주시면 됩니다.

strings /usr/bin/nvidia-smi | grep "/opt/ss"

 

해당 이슈는 nvidia-smi 바이너리 자체가 /opt/ss를 실행하도록 조작되었기 때문에 발생한 것으로 정리할 수 있을 것 같습니다.

2. Failed to initialize NVML: Driver/library version mismatch

nvidia-smi 실행 시, 발생했던 에러입니다.

해당 경우에는 심볼릭 링크가 이전 라이브러리 버전을 가리키고 있어서 생기는 문제라고 합니다.

 

1. libnvidia-ml.so.1 -> 가 가리키는 버전으로 현재 라이브러리 버전을 확인합니다. (NVML 관련 라이브러리 파일과 심볼릭 링크들을 확인하는 명령어입니다.)

ls -l /usr/lib/x86_64-linux-gnu/libnvidia-ml.so*

 

2. Driver Version: 을 통해 드라이버 버전 확인합니다.

nvidia-smi

 

해당 오류 발생 시, 현재 라이브러리 버전과 드라이버 버전이 다르게 출력됩니다.

3. 시스템이 참조하고 있는 NVML 라이브러리 버전을 실제 드라이버 버전과 일치하도록 맞춰줍니다. (드라이버 버전을 예시로 535.171.04를 넣었습니다.)

sudo ln -sf /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.535.171.04 \
             /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1
sudo ldconfig

 

위 방법이 안되면 드라이버 재설치를 진행해줍니다.

sudo apt purge '*nvidia*'
sudo apt autoremove
sudo reboot
sudo apt update
sudo apt install nvidia-driver-535

 

제 경우에는 다행히 드라이버 재설치까지는 진행하지 않고 잘 해결되었습니다.

 

3. cupy.cuda.runtime.CUDARuntimeError: cudaErrorUnknown: unknown error

CuPy를 이용한 GPU 연산 수행 시, 발생했던 오류입니다.

원인은 컨테이너 내부에서 CUDA 라이브러리 경로가 잘못 설정되어 있는 경우이거나 NVIDIA UVM 모듈(nvidia_uvm)이 제대로 로드되지 않기 때문이라고 하네요.

 

1. 컨테이너 내부에서 CUDA 라이브러리 경로(LD_LIBRARY_PATH)를 재설정 해주세요. cuda 버전은 적절히 수정해서 사용하시길 바랍니다.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda-12.2/compat

 

2. 호스트에서 UVM 모듈(nvidia_uvm)을 재설치 해주세요.

sudo rmmod nvidia_uvm
sudo modprobe -r nvidia_uvm && sudo modprobe nvidia_uvm

 

해당 경우에는 관련 자료를 참고해서 해결했습니다.

자세한 내용은 링크를 참고해주세요.

 

RuntimeError: CUDA unknown error · Issue #49081 · pytorch/pytorch

 

CUDA initialization: CUDA unknown error - this may be due to an incorrectly set up environment