Ollama Docker 컨테이너가 GPU 대신 CPU를 쓴다면 호스트 드라이버 → NVIDIA Container Toolkit → 컨테이너 GPU 전달 → Ollama 로그와 ollama ps 순서로 확인하면 된다. 호스트의 nvidia-smi부터 실패하면 Docker 설정을 고칠 단계가 아니다. 테스트 컨테이너에서는 GPU가 보이는데 Ollama만 CPU를 쓴다면 지원 드라이버·GPU, Jetson 환경변수, 모델·컨텍스트의 VRAM 초과를 분리해 봐야 한다.

먼저 GPU 미인식과 VRAM 부족을 구분한다

“GPU를 안 쓴다”는 증상은 하나가 아니다. GPU 자체가 컨테이너에 전달되지 않은 경우, Ollama가 GPU를 발견하지 못한 경우, GPU는 정상 감지됐지만 모델이나 컨텍스트가 커서 일부 레이어를 CPU에 둔 경우가 서로 다른 해결책을 요구한다. 성능이 느리다는 느낌만으로 드라이버를 다시 설치하지 말고 관찰값부터 분류해야 한다.

관찰값	판정	다음 단계
호스트 nvidia-smi 실패	호스트 드라이버·커널 문제	Docker보다 드라이버 상태를 먼저 복구
호스트 성공, 테스트 컨테이너 실패	Container Toolkit·Docker runtime 문제	runtime 구성과 Docker 재시작
테스트 컨테이너 성공, Ollama 컨테이너 실패	GPU 전달 옵션·Ollama 감지 문제	컨테이너 재생성·로그 확인
ollama ps에 CPU/GPU 혼합	VRAM 초과에 따른 부분 오프로딩 가능성	모델·컨텍스트·동시 실행량 축소
절전 복귀 뒤 갑자기 CPU 사용	NVIDIA UVM 드라이버 문제 가능성	공식 안내의 UVM 재로드 검토

1단계: 호스트에서 드라이버와 지원 조건을 확인한다

Linux 호스트에서 다음 명령이 GPU 이름, 드라이버 버전, 메모리 상태를 반환해야 한다. 여기서 실패하면 컨테이너는 정상 GPU 장치를 받을 수 없다. Ollama 공식 하드웨어 문서는 현재 NVIDIA compute capability 5.0 이상과 드라이버 550 이상을 지원 기준으로 안내하며, compute capability 5.0~6.2 GPU에는 드라이버 570 이상을 요구한다. 실제 GPU의 compute capability와 드라이버 조합을 공식 목록에서 다시 확인해야 한다.

nvidia-smi
nvidia-smi -L
cat /proc/driver/nvidia/version
sudo systemctl status docker --no-pager
docker version

• nvidia-smi 자체가 없다: NVIDIA 드라이버 설치가 끝나지 않았거나 실행 경로에 없다.
• GPU가 보이지만 드라이버가 지원 기준보다 낮다: 배포판의 공식 패키지 방식으로 호환 드라이버를 갱신한다.
• 절전 복귀 후만 실패한다: Ollama 공식 문서는 Linux suspend/resume 뒤 NVIDIA GPU discovery가 실패할 수 있다고 설명하며 nvidia_uvm 재로드를 우회책으로 제시한다.
• 가상머신이다: 게스트 OS에 GPU가 실제 passthrough됐는지 확인한다. 호스트에 GPU가 있다는 사실만으로 게스트 컨테이너에 전달되지는 않는다.

2단계: Ollama보다 먼저 테스트 컨테이너에서 GPU를 확인한다

호스트 GPU가 정상이면 NVIDIA Container Toolkit 계층만 분리해서 테스트한다. Ollama 공식 Docker 문서는 Toolkit 설치 후 nvidia-ctk로 Docker runtime을 구성하고 Docker를 재시작하도록 안내한다. 재시작을 빼먹으면 설치 파일은 있어도 실행 중 daemon 설정에는 반영되지 않을 수 있다.

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all ubuntu nvidia-smi
docker info | grep -i -E 'runtime|nvidia'
sudo nvidia-ctk runtime configure --runtime=docker --dry-run

테스트 컨테이너의 nvidia-smi가 실패하면 Ollama 이미지를 교체해도 해결되지 않는다. 이 단계에서는 Toolkit 패키지, Docker daemon 설정, cgroup·CDI 구성, 호스트 보안 정책을 점검한다. NVIDIA 공식 설치 문서는 systemd cgroup 환경에서 daemon-reload 뒤 컨테이너가 GPU 접근을 잃는 알려진 조건도 안내하므로 재현 시 해당 문서의 최신 제한사항을 확인해야 한다.

3단계: Ollama 컨테이너를 GPU 옵션과 함께 재생성한다

기존 CPU 전용 컨테이너에 설정만 덧붙이는 것보다 정확한 GPU 옵션으로 재생성하는 편이 확실하다. 공식 Ollama Docker 명령은 --gpus=all을 사용한다. Compose에서는 현재 Docker Compose가 지원하는 gpus: all 또는 GPU device reservation을 사용할 수 있지만, 배포 서버의 Compose 버전이 해당 문법을 지원하는지 먼저 확인해야 한다.

docker rm -f ollama 2>/dev/null || true

docker run -d   --gpus=all   -v ollama:/root/.ollama   -p 11434:11434   --name ollama   --restart unless-stopped   ollama/ollama

services:
  ollama:
    image: ollama/ollama
    gpus: all
    volumes:
      - ollama:/root/.ollama
    ports:
      - "11434:11434"
    restart: unless-stopped

volumes:
  ollama:

1. 컨테이너를 재생성한다. Compose 파일만 바꾸고 기존 컨테이너를 그대로 두지 않는다.
2. 컨테이너 안에서 장치 노출을 확인한다. NVIDIA 테스트는 호스트와 별도로 성공해야 한다.
3. Ollama 서버 로그를 확인한다. GPU inventory와 초기화 오류 코드를 찾는다.
4. 작은 모델을 한 번 실행한다. 모델을 로드하지 않은 상태의 낮은 GPU 사용률만 보고 실패로 판단하지 않는다.
5. ollama ps에서 processor를 확인한다. CPU 100%, GPU 100%, 혼합 상태를 구분한다.

docker inspect ollama --format '{{json .HostConfig.DeviceRequests}}'
docker logs --tail 200 ollama
docker exec ollama ollama run llama3.2:3b "한 문장으로 답해줘: GPU 확인"
docker exec ollama ollama ps
watch -n 1 nvidia-smi

4단계: Ollama 로그의 GPU discovery 오류를 읽는다

Ollama 공식 troubleshooting 문서는 GPU 초기화 실패가 서버 로그에서 오류 코드 3, 46, 100, 999 등으로 보일 수 있다고 설명한다. 숫자 하나를 만능 원인으로 해석하면 안 되며, 같은 시점의 드라이버 로그와 컨테이너 GPU 테스트 결과를 함께 봐야 한다.

로그·상태	의미 후보	확인할 것
no device·오류 100	GPU 장치가 보이지 않음	--gpus, DeviceRequests, 테스트 컨테이너
not initialized·오류 3	드라이버 초기화 실패	호스트 드라이버, UVM, 커널 로그
device unavailable·오류 46	장치 사용 불가	다른 프로세스·드라이버 상태·재부팅 필요성
unknown·오류 999	범용 NVIDIA 오류	dmesg, journalctl, 드라이버 재로드
GPU 감지 성공+CPU/GPU 혼합	부분 오프로딩 가능성	VRAM, 모델 크기, 컨텍스트, 병렬 실행

docker logs ollama 2>&1 | grep -i -E 'gpu|cuda|nvidia|vram|library|error'
dmesg | grep -i -E 'nvrm|xid|nvidia' | tail -n 100
journalctl -u docker --since '-15 min' --no-pager

운영 서버에서 커널 모듈을 내리는 명령은 실행 중인 GPU 작업을 중단할 수 있다. Ollama 공식 문서의 sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm는 절전 복귀 문제의 우회책이지 모든 GPU 오류에 먼저 적용할 명령이 아니다. 다른 CUDA 작업이 없는지 확인하고 유지보수 시간에 판단해야 한다.

GPU가 일부만 사용되면 모델·컨텍스트·동시성을 줄인다

GPU가 정상 감지됐는데 ollama ps가 CPU와 GPU 혼합을 표시하거나 시스템 RAM 사용량이 커진다면 컨테이너 passthrough보다 메모리 예산 문제일 가능성이 높다. 모델 가중치뿐 아니라 KV 캐시와 컨텍스트, 동시 요청이 VRAM을 사용한다. 최근 공개 Ollama 이슈에서도 큰 컨텍스트 메타데이터로 소비자 하드웨어에서 OOM이 발생하거나 GPU 메모리를 일부만 쓰고 시스템 RAM으로 넘어간다는 질문이 반복됐다. 이 사례는 수요 신호일 뿐, 모든 환경의 원인으로 단정할 수 없다.

• 더 작은 양자화·모델로 비교한다. 같은 컨테이너에서 작은 모델이 GPU 100%라면 passthrough 자체는 정상일 가능성이 높다.
• 컨텍스트를 낮춘다. 긴 컨텍스트는 KV 캐시를 키우므로 작업에 필요한 범위로 제한한다.
• 동시 실행 모델과 요청을 줄인다. 여러 모델을 유지하거나 병렬 요청을 늘리면 가용 VRAM이 나뉜다.
• nvidia-smi와 ollama ps를 함께 본다. 순간 utilization만이 아니라 VRAM 점유와 Ollama processor 표시를 비교한다.
• 기존 메모리 계산과 연결한다. 로컬 LLM RAM·VRAM 계산 가이드에서 모델 크기와 KV 캐시 예산을 먼저 잡는 편이 낫다.

Jetson과 AMD는 NVIDIA 데스크톱 절차를 그대로 쓰면 안 된다

Ollama 공식 Docker 문서는 NVIDIA JetPack 시스템에서 버전을 자동 발견하지 못하므로 JETSON_JETPACK=5 또는 JETSON_JETPACK=6을 컨테이너에 전달하도록 안내한다. 최근 JetPack 7.2·Orin 환경의 공개 이슈에서는 네이티브와 Docker 모두 CUDA 오류가 발생해, 컨테이너 설정만으로 설명할 수 없는 호환성 문제도 확인됐다. 공식 지원 범위와 해당 릴리스 상태를 확인하기 전 임의 환경변수로 새 JetPack 세대를 가장하면 안 된다.

-d -e JETSON_JETPACK=6 --gpus=all ... ollama/ollama

docker run -d   --device /dev/kfd   --device /dev/dri   -v ollama:/root/.ollama   -p 11434:11434   --name ollama   ollama/ollama:rocm

AMD는 NVIDIA Toolkit과 nvidia-smi가 아니라 ROCm 지원 GPU·드라이버와 장치 전달을 확인한다. Ollama 공식 하드웨어 문서는 Linux에서 현재 AMD ROCm v7 드라이버를 요구하며, 추가 AMD GPU에는 Vulkan 경로를 제공한다. GPU 제조사와 운영체제에 맞는 분기를 선택해야 한다.

환경별 빠른 선택표

환경	첫 명령	컨테이너 설정	실패 시 우선순위
Linux+NVIDIA	nvidia-smi	Toolkit + --gpus=all	드라이버 → runtime → Ollama 로그
Jetson	JetPack 버전 확인	공식 지원 범위의 JETSON_JETPACK	JetPack·Ollama 호환성
Linux+AMD	ROCm 장치·드라이버 확인	ROCm 이미지 + /dev/kfd, /dev/dri	ROCm 지원 목록·권한
Windows Docker Desktop	호스트 GPU·WSL 상태 확인	Desktop GPU 통합과 Linux 컨테이너	WSL·Desktop·드라이버 계층
가상머신	게스트에서 GPU 확인	게스트 Docker runtime	하이퍼바이저 passthrough

Docker host 자체가 메모리 부족으로 불안정하다면 Docker Compose 메모리 제한과 OOM 가이드도 함께 확인해야 한다. GPU 감지 실패와 호스트 OOM은 증상이 느린 응답·컨테이너 재시작으로 겹칠 수 있지만 진단 계층은 다르다.

10분 진단 체크리스트

1. 1분: 호스트 nvidia-smi와 드라이버 버전을 기록한다.
2. 2분: docker run --rm --gpus all ubuntu nvidia-smi를 실행한다.
3. 2분: docker inspect로 Ollama 컨테이너의 DeviceRequests를 확인한다.
4. 2분: 작은 모델을 실행하면서 docker logs, ollama ps, nvidia-smi를 함께 본다.
5. 1분: Jetson·AMD·VM이면 해당 환경 분기로 이동한다.
6. 2분: 감지는 성공했지만 혼합 실행이면 모델·컨텍스트·동시성을 한 단계 낮춰 비교한다.

최종 기록에는 호스트 OS, GPU, 드라이버, Docker·Ollama 버전, 실행 명령, 테스트 컨테이너 결과, Ollama 로그, ollama ps를 남긴다. 그래야 드라이버 문제와 Ollama 회귀, 모델별 메모리 문제를 재현 가능한 형태로 구분할 수 있다.

FAQ

nvidia-smi는 되는데 Ollama만 CPU를 쓰는 이유는 무엇인가

호스트 GPU 확인만 통과했고 컨테이너 GPU 전달이 빠졌거나, Ollama가 장치를 초기화하지 못했거나, 모델·컨텍스트가 VRAM을 초과했을 수 있다. 테스트 컨테이너, DeviceRequests, Ollama 로그, ollama ps 순서로 범위를 좁혀야 한다.

GPU 사용률이 0%면 무조건 미인식인가

아니다. 모델이 로드되지 않았거나 요청 사이 유휴 상태일 수 있다. 실제 추론 중 nvidia-smi의 VRAM·utilization과 ollama ps의 processor를 함께 확인해야 한다.

privileged: true를 넣으면 해결되는가

진단 없이 사용할 해결책이 아니다. 필요한 GPU device request보다 훨씬 넓은 권한을 준다. NVIDIA Container Toolkit과 --gpus 또는 Compose GPU 설정으로 필요한 장치만 전달해야 한다.

JetPack 7에서도 JETSON_JETPACK=6을 넣으면 되는가

공식 문서가 안내한 값의 범위를 넘어 임의로 가장하면 안 된다. 최근 JetPack 7.2 공개 이슈는 네이티브와 Docker 모두 오류가 난 사례이므로 최신 Ollama 지원 상태와 릴리스 이슈를 확인해야 한다.

참고 자료

• Ollama Docker 공식 문서
• Ollama Hardware support
• Ollama Troubleshooting
• NVIDIA Container Toolkit 설치 가이드
• Docker Compose GPU support
• JetPack 7.2·Orin GPU 미인식 공개 이슈
• 큰 컨텍스트와 OOM 관련 공개 이슈
• 부분 GPU 메모리 사용 관련 공개 이슈

공식 문서와 공개 이슈 확인 기준일은 2026년 8월 30일이다. 공개 이슈는 사용자 수요와 재현 사례를 보여 주는 자료이며, 해결책과 모든 환경의 원인을 확정하는 근거로 사용하지 않았다.