엔비디아 드라이버만 설치하면 Docker 컨테이너에서도 GPU가 저절로 잡힌다고 생각하는 분들이 의외로 많습니다. 실제로는 호스트 드라이버, nvidia-container-toolkit, Docker 런타임 설정이라는 세 개의 층이 각각 맞물려야 컨테이너 안에서 GPU가 인식됩니다. Docker에서 GPU가 안 잡히는 문제는 대부분 이 세 층 중 어디가 빠졌는지 순서대로 확인하면 원인을 좁힐 수 있어요.
이 글에서는 실무에서 흔히 놓치는 지점을 순서대로, 그리고 어떤 명령어로 무엇을 확인해야 하는지 구체적으로 정리했습니다. Ubuntu/Debian 계열 Linux 호스트에 Docker Engine을 직접 설치한 환경을 기준으로 하며, WSL2나 클라우드 GPU 인스턴스에서 달라지는 부분은 별도로 짚었습니다.
1단계, 호스트에서 드라이버부터 확인해야 하는 이유
컨테이너는 자체 GPU 드라이버를 갖지 않습니다. 커널 모듈 수준의 드라이버는 반드시 호스트에 설치돼 있어야 하고, 컨테이너는 그 드라이버를 공유해서 씁니다. 그래서 가장 먼저 할 일은 컨테이너가 아니라 호스트에서 GPU가 정상 인식되는지 보는 것입니다.
nvidia-smi이 명령이 호스트 터미널에서 드라이버 버전과 GPU 목록을 정상 출력하면 1단계는 통과입니다. command not found가 뜨거나 NVIDIA-SMI has failed류 에러가 나오면, Docker 설정을 아무리 손봐도 컨테이너에서 GPU가 잡히지 않습니다. 이 경우 문제는 Docker가 아니라 호스트 드라이버 설치 자체이므로 방향을 바꿔야 합니다.
WSL2 환경이라면 조금 다릅니다. WSL2 안에는 별도의 Linux용 NVIDIA 드라이버를 설치하지 않고, Windows 쪽에 설치된 드라이버를 WSL이 그대로 넘겨받는 구조입니다. WSL2 안에서 nvidia-smi가 안 되면 Windows 호스트의 그래픽 드라이버 버전부터 확인하는 게 순서상 맞습니다.
2단계, nvidia-container-toolkit이 실제로 설치돼 있나요?
호스트 드라이버가 정상이어도 Docker는 기본적으로 GPU 장치를 컨테이너에 넘기는 방법을 모릅니다. 이 역할을 하는 게 NVIDIA에서 배포하는 nvidia-container-toolkit입니다. 예전에는 nvidia-docker2 패키지 이름으로 불리던 것이 지금은 이 이름으로 통합됐습니다.
설치 여부는 패키지 조회로 바로 확인할 수 있습니다.
dpkg -l | grep nvidia-container-toolkit아무 결과도 안 나오면 설치가 안 된 상태입니다. Ubuntu/Debian 기준 설치 절차는 NVIDIA 공식 저장소를 등록한 뒤 진행합니다.
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설치 명령과 지원 배포판 목록은 계속 갱신되므로, 정확한 최신 절차는 NVIDIA Container Toolkit 설치 가이드에서 자신의 OS 항목을 그대로 따라가는 게 안전합니다. 배포판 버전이 바뀌면 저장소 URL 표기가 달라지는 경우가 있어서, 블로그 글의 명령을 그대로 복붙하는 것보다 공식 문서를 한 번 대조하는 편을 권합니다.
3단계, 런타임 설정이 빠지면 toolkit을 설치해도 소용없는 이유
nvidia-container-toolkit을 설치하는 것과, Docker 데몬이 그 런타임을 쓰도록 등록하는 것은 별개 작업입니다. 이 부분을 빠뜨려서 “분명 설치했는데 안 된다”는 상황이 자주 생깁니다. 설치 직후에는 아래 명령으로 Docker 데몬 설정에 nvidia 런타임을 등록해야 합니다.
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker이 명령은 /etc/docker/daemon.json 파일에 아래와 비슷한 내용을 자동으로 써 넣습니다.
{
"runtimes": {
"nvidia": {
"path": "nvidia-container-runtime",
"runtimeArgs": []
}
}
}systemctl restart docker를 빼먹으면 daemon.json이 바뀌어도 실행 중인 Docker 데몬에는 반영되지 않습니다. 재시작을 했는데도 여전히 안 되면 docker info로 실제 등록된 런타임 목록을 확인해 보세요.
docker info | grep -i runtime출력에 nvidia가 보이지 않으면 daemon.json 수정이 반영되지 않은 것이므로, 파일 문법 오류(JSON 콤마 누락 등)부터 의심해야 합니다.
4단계, –gpus 옵션과 compose 설정을 이 순서로 테스트해 보세요
여기까지 마쳤다면 실제 컨테이너 실행으로 검증할 차례입니다. Docker Engine 19.03부터는 --runtime=nvidia를 매번 지정하지 않고 --gpus 플래그로 GPU를 넘길 수 있습니다.
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi이 명령이 컨테이너 안에서 GPU 목록과 드라이버 버전을 출력하면 4단계까지 정상입니다. 여기서 CUDA 초기화 에러가 나온다면, 이미지 태그가 요구하는 CUDA 버전이 호스트 드라이버가 지원하는 범위보다 높을 가능성이 큽니다. 정확한 최소 드라이버 버전은 이미지 버전마다 다르므로 Docker 공식 GPU 리소스 문서의 안내를 참고해서 이미지 태그를 낮추거나 드라이버를 올리는 쪽으로 맞추는 게 좋습니다.
docker-compose를 쓴다면 --gpus 플래그 대신 deploy.resources.reservations.devices 항목으로 선언합니다.
services:
app:
image: nvidia/cuda:12.4.1-base-ubuntu22.04
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]주의할 점은, docker-compose up을 일반 실행 모드로 쓸 때는 deploy 항목이 Swarm 전용으로 취급돼 무시되는 버전이 있었다는 것입니다. Compose V2(현재 docker compose 서브커맨드) 기준으로는 이 필드가 로컬 실행에서도 인식되지만, 오래된 docker-compose 1.x 바이너리를 그대로 쓰고 있다면 runtime: nvidia와 environment: NVIDIA_VISIBLE_DEVICES=all 조합으로 바꿔야 동작하는 경우가 있으니 Compose 버전도 함께 확인해 보세요.
이 순서대로 해도 안 잡히는 경우가 있습니다
위 네 단계를 모두 통과했는데도 GPU가 안 잡히는 경우가 실제로 있습니다. 대표적인 예를 정리하면 아래와 같습니다.
| 상황 | 증상 | 해결 방향 |
|---|---|---|
| Secure Boot 활성화 | nvidia 커널 모듈 로드 실패, 호스트 nvidia-smi부터 안 됨 | MOK 서명 등록 또는 Secure Boot 비활성화 |
| macOS Docker Desktop | --gpus all 옵션 자체를 인식 못 함 |
리눅스 VM 기반 구조상 GPU 패스스루 미지원, 대안으로 Docker Model Runner 등 별도 경로 검토 |
| rootless Docker | nvidia 런타임 등록해도 권한 오류 | rootless 모드는 nvidia-container-toolkit의 일부 기능 제약이 있어 별도 설정 필요 |
| Podman 사용 | Docker용 가이드 그대로 따라 해도 안 됨 | --hooks-dir 등 Podman 전용 옵션으로 다시 설정 |
| Compose deploy 필드 무시 | 설정은 맞는데 컨테이너 안에서 GPU 없음 | Compose 버전이 낮으면 runtime: nvidia 방식으로 대체 |
이 표에서 보듯 macOS는 아예 구조적으로 GPU 패스스루를 지원하지 않는 케이스이므로, 앞의 1~4단계를 아무리 반복해도 해결되지 않습니다. 이럴 때는 문제 해결 방향을 Docker 설정이 아니라 실행 환경 자체를 바꾸는 쪽으로 돌려야 합니다.
호스트 nvidia-smi는 되는데 컨테이너에서는 안 될 때
이 질문이 가장 많이 들어옵니다. 호스트에서는 GPU가 멀쩡히 잡히는데 컨테이너 안에서만 nvidia-smi 명령 자체가 없다거나 GPU 목록이 비어 있는 경우입니다.
먼저 이미지 안에 nvidia-smi 바이너리가 없는 게 정상인 이미지인지부터 확인해야 합니다. nvidia/cuda:*-base-* 계열 이미지는 nvidia-smi를 포함하지만, 순수 Python이나 일반 Ubuntu 베이스 이미지에서 --gpus all만 붙였다고 nvidia-smi 명령이 생기지는 않습니다. GPU 장치 자체는 넘어가지만 유틸리티 바이너리는 이미지에 별도로 포함돼 있어야 합니다.
바이너리는 있는데 GPU 목록이 비어 있다면, 2단계와 3단계를 다시 확인하는 게 순서입니다. docker info | grep -i runtime 결과에 nvidia가 없거나, --gpus 플래그 자체를 빼먹고 실행했을 가능성이 가장 흔합니다.
