Docker NVIDIA Container Toolkit Kurulumu: Ubuntu 22.04, 24.04 ve 26.04

Kısa cevap

NVIDIA Container Toolkit, Docker konteynerlerinin sunucudaki NVIDIA GPU'ları kullanmasını sağlayan NVIDIA paketidir. Ubuntu 22.04, 24.04 veya 26.04'te kurulumu dört adımdır: sürücüyü doğrulayın, NVIDIA'nın apt deposundan nvidia-container-toolkit paketini kurun, sudo nvidia-ctk runtime configure --runtime=docker ile Docker'ı yapılandırıp yeniden başlatın ve docker run --rm --gpus all ubuntu nvidia-smi ile test edin. Ekim 2026 itibarıyla güncel sürüm 1.20.1'dir.

• Sunucuya CUDA Toolkit kurmanız gerekmez; yalnızca NVIDIA sürücüsü gerekir. CUDA kütüphaneleri imajın içinden gelir.
• CUDA 13.x imajları için sürücü sürümü 580 veya üzeri olmalıdır.
• Toolkit 1.18'den beri CDI tanımını kendisi üretir; Docker 28.3.0 ve sonrasında GPU'yu --device nvidia.com/gpu=all ile de isteyebilirsiniz.

Kurulumdan önce sunucuda ne hazır olmalı?

Çalışan bir NVIDIA sürücüsü ve Docker Engine yeterlidir. NVIDIA'nın kendi deposundaki notta da belirtildiği gibi ana makineye (host) CUDA Toolkit kurmanıza gerek yoktur.

nvidia-smi          # GPU'lar ve sürücü sürümü listelenmeli
docker --version    # Docker Engine kurulu olmalı

nvidia-smi çalışmıyorsa önce sürücüyü kurun; Ubuntu'daki adımları PyTorch GPU kurulum rehberimizde anlattık. Docker'ı, Docker'ın resmi apt deposundan kurun: Ubuntu'nun docker.io paketi, Docker belgelerinde resmi paketlerle çakışan paketler arasında sayılır. NVIDIA'nın test ettiği dağıtımlar arasında Ubuntu 22.04, 24.04 ve 26.04 var.

Sürücü sürümü, konteynerde hangi CUDA sürümünü kullanabileceğinizi belirler. NVIDIA'nın CUDA sürüm notlarına göre eşleşme şöyle:

CUDA alt sürüm uyumluluğu (minor version compatibility) sayesinde 13.x uygulamaları 580 ve üzeri sürücülerde çalışır; 13.4'ün yeni özellikleri ise R615 ister. nvidia-smi çıktısının üst satırındaki "CUDA Version" değeri, sürücünüzün desteklediği en yüksek CUDA sürümünü gösterir (NVIDIA'nın güncel belgelerinde bu alanın yeni adı "CUDA UMD Version").

NVIDIA Container Toolkit nasıl kurulur?

NVIDIA'nın apt deposunu ekleyip dört paketi aynı sürümde kurarsınız. Komutlar NVIDIA'nın kurulum kılavuzundan alındı:

sudo apt-get update && sudo apt-get install -y --no-install-recommends ca-certificates curl gnupg2

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

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.1-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

nvidia-ctk --version

Sürümü sabitlemek, aynı kurulumu başka sunucularda tekrarlamayı kolaylaştırır; sabitlemeden sudo apt-get install -y nvidia-container-toolkit yazarsanız en son sürüm kurulur. Toolkit 1.18'den beri libnvidia-container* paketlerinin sürümü nvidia-container-toolkit* paketleriyle birebir aynı olmak zorunda, bu yüzden güncellerken dört paketi birlikte güncelleyin. Eski rehberlerde geçen nvidia-docker / nvidia-docker2 kurulumu artık gerekmiyor; bu paketler kullanımdan kalktı ve işlevleri yukarıdaki dört pakete taşındı.

Docker nasıl yapılandırılır?

nvidia-ctk, Docker'ın /etc/docker/daemon.json dosyasına NVIDIA çalışma zamanını (runtime) ekler; ardından Docker'ı yeniden başlatırsınız:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info | grep -i runtimes    # listede "nvidia" görünmeli

Komut, dosyadaki mevcut ayarlara dokunmadan şu bloğu ekler:

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

NVIDIA çalışma zamanını varsayılan yapmanız gerekiyorsa (ör. Docker kullanan bir Kubernetes kurulumunda) komuta --set-as-default ekleyin; dosyaya "default-runtime": "nvidia" satırı yazılır. Her komutta sudo yazmamak için kullanıcınızı docker grubuna ekleyebilirsiniz (sudo usermod -aG docker $USER), ancak Docker'ın uyardığı gibi bu grup root düzeyinde yetki verir.

Kurulum nasıl test edilir?

NVIDIA'nın örnek komutu düz bir Ubuntu imajında nvidia-smi çalıştırır; çıktı, sunucuda gördüğünüz tablonun aynısı olmalıdır:

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

İmajda sürücü yoktur; toolkit, sürücü kütüphanelerini ve nvidia-smi aracını konteyner başlarken içeri bağlar. Ardından CUDA'lı bir imajla deneyin; bu test, imajın CUDA sürümünün sürücünüzle uyumlu olduğunu da doğrular:

docker run --rm --gpus all nvidia/cuda:13.0.3-base-ubuntu24.04 nvidia-smi

nvidia/cuda imajlarında latest etiketi yoktur; etiketi her zaman açıkça yazın. Belirli GPU'ları seçmek, Docker Compose ve imaj seçimi gibi günlük kullanım konuları için Docker'da GPU kullanımı rehberimize bakın.

Toolkit konteynere varsayılan olarak yalnızca compute ve utility sürücü yeteneklerini verir; CUDA ve nvidia-smi için bu yeterlidir. NVENC/NVDEC ile video kodlayacaksanız video yeteneğini de isteyin (GPU ile video transcoding rehberimiz). JupyterLab'i GPU'lu bir konteynerde açacaksanız portu yalnızca 127.0.0.1 adresine yayımlayın; ayrıntılar Jupyter ile bulut GPU rehberimizde.

CDI nedir, ne zaman kullanılmalı?

CDI (Container Device Interface), bir cihazın konteynere nasıl verileceğini tanımlayan açık bir standarttır; Docker, Podman ve containerd aynı tanım dosyasını okur. Toolkit 1.18'den beri nvidia-cdi-refresh adlı systemd servisi bu dosyayı (/var/run/cdi/nvidia.yaml) kurulumda, sürücü güncellemesinde ve her açılışta kendisi üretir.

nvidia-ctk cdi list
# nvidia.com/gpu=0
# nvidia.com/gpu=GPU-...
# nvidia.com/gpu=all

docker run --rm --device nvidia.com/gpu=all ubuntu nvidia-smi -L

Docker belgelerine göre CDI, Docker Engine 28.3.0 ve sonrasında varsayılan olarak açıktır. Daha eski bir sürüm kullanıyorsanız (CDI için en az Docker 25 gerekir) sudo nvidia-ctk runtime configure --runtime=docker --cdi.enabled komutu daemon.json'a "features": {"cdi": true} ekler; sonra Docker'ı yeniden başlatın.

CDI'ın pratik bir avantajı var: cgroup'ların systemd ile yönetildiği sistemlerde --gpus ile başlatılan konteynerler, sunucuda systemctl daemon-reload çalıştığında GPU erişimini kaybedebilir; CDI ile başlatılanlar bundan etkilenmez. MIG bölümlerini yeniden yapılandırdığınızda ya da sürücüyü kaldırdığınızda tanım dosyası kendiliğinden yenilenmez; sudo systemctl restart nvidia-cdi-refresh.service ile yenileyin.

Rootless Docker'da ne değişir?

Docker'ı root yetkisi olmadan (rootless) çalıştırıyorsanız yapılandırma kullanıcı dizininizdeki daemon.json'a yazılır ve toolkit'in cgroup yönetimi kapatılır. NVIDIA'nın kılavuzundaki üç komut:

nvidia-ctk runtime configure --runtime=docker --config=$HOME/.config/docker/daemon.json
systemctl --user restart docker
sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place

NVIDIA, CDI'ın rootless konteynerlerle uyumluluğu artırdığını da belirtiyor; rootless kurulumlarda CDI'yı denemeye değer.

containerd, Kubernetes ve Podman'da durum ne?

Toolkit diğer konteyner motorlarıyla da çalışır; fark, yapılandırma komutunda ve GPU'yu isteme biçimindedir:

containerd ve CRI-O'da yapılandırmadan sonra servisi yeniden başlatın (sudo systemctl restart containerd ya da crio). Podman için NVIDIA'nın test komutu:

podman run --rm --device nvidia.com/gpu=all --security-opt=label=disable ubuntu nvidia-smi -L

Sık karşılaşılan hatalar nasıl çözülür?

Hataların çoğu eksik yapılandırmadan, eski depo dosyalarından ya da sürücü ile imaj arasındaki sürüm farkından kaynaklanır:

"could not select device driver" hatası nasıl çözülür?

docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]] hatası, Docker'ın --gpus isteğini karşılayacak NVIDIA çalışma zamanını bulamadığı anlamına gelir. Sırayla şunları kontrol edin:

1. Toolkit kurulu mu? nvidia-ctk --version bir sürüm numarası yazmalı; yazmıyorsa yukarıdaki kurulum adımlarını uygulayın.
2. Docker yapılandırıldı mı? docker info | grep -i runtimes çıktısında nvidia görünmeli; görünmüyorsa sudo nvidia-ctk runtime configure --runtime=docker çalıştırın.
3. Docker yeniden başlatıldı mı? Yapılandırmadan sonra sudo systemctl restart docker gerekir.
4. Ayar doğru dosyaya mı yazıldı? Rootless Docker'da ayar /etc/docker/daemon.json dosyasına değil, ~/.config/docker/daemon.json dosyasına yazılmalıdır (rootless bölümüne bakın).

"Conflicting values set for option Signed-By" hatası

Çakışan liste dosyalarını bulmak için NVIDIA'nın önerdiği komut:

grep -l "nvidia.github.io" /etc/apt/sources.list.d/* | grep -vE "/nvidia-container-toolkit.list\$"

Sorun sürüyorsa: ayrıntılı günlük

Sorun sürüyorsa çalışma zamanının ayrıntılı günlüğünü açıp hatayı yeniden üretin:

sudo nvidia-ctk config --in-place \
    --set nvidia-container-runtime.log-level=debug \
    --set nvidia-container-runtime.debug=/var/log/nvidia-container-runtime.log

NVIDIA'nın sorun giderme sayfasındaki yol da aynı sonucu verir: /etc/nvidia-container-runtime/config.toml dosyasındaki debug satırının başındaki # işaretini kaldırın.

Bu iş için hangi GPU?

Bu rehberdeki adımlar sunduğumuz tüm modellerde aynıdır; GPU'lar size ayrılır, başka müşterilerle paylaşılmaz. Konteyner tabanlı geliştirme ve test için RTX PRO 4000 (24 GB, aylık $450), 7–14B parametreli modellerle çalışan servisler için L40S (48 GB, aylık $900) iyi başlangıç noktalarıdır. Tek siparişte en fazla 8 GPU alabilirsiniz. İş yüküne göre önerdiğimiz kartları hizmetler sayfamızda bulabilirsiniz. vLLM ya da SGLang'in hazır Docker imajlarıyla model sunacaksanız GPU ve bellek seçimini LLM inference sayfamızda anlattık.

Sunucu kaynakları GPU belleğine göre baştan bellidir: Her 4 GB GPU belleği için 1 CPU çekirdeği ve GPU belleğinin 1,5 katı RAM verilir; 1 TB SSD ve size özel bir IP adresi her siparişe dahildir. Büyük konteyner imajları ve veri setleri için disk ihtiyacınızı sipariş formundaki mesaj alanına yazın. Kiralama aylıktır (en az 1 ay); fiyatlar GPU başına, ABD doları cinsinden ve KDV hariçtir, fatura kesim tarihindeki TCMB satış kuruyla TL olarak düzenlenir; tüm modellerin fiyatları fiyat listesinde. Yalnızca birkaç saatlik bir deneme yapacaksanız saatlik bir bulut hizmeti daha ucuz olabilir.

Özet

• Docker'da GPU kullanmak için ana makinede NVIDIA sürücüsü ve NVIDIA Container Toolkit yeterlidir; CUDA Toolkit gerekmez.
• Kurulum sırası: apt deposu, dört paket (Ekim 2026'da 1.20.1), nvidia-ctk runtime configure --runtime=docker, Docker'ı yeniden başlatma, nvidia-smi testi.
• CUDA 13.x imajları için sürücü 580 veya üzeri olmalıdır; 13.4'ün yeni özellikleri R615 ister.
• Toolkit 1.18 ve sonrası CDI tanımını otomatik üretir; Docker 28.3.0+ ve Podman'da GPU --device nvidia.com/gpu=all ile istenebilir.
• En sık hatalar eksik yapılandırma, eski depo dosyaları ve sürücü ile imaj arasındaki CUDA sürümü farkıdır.

Kaynaklar

• NVIDIA: Installing the NVIDIA Container Toolkit
• NVIDIA: Support for Container Device Interface
• NVIDIA: Container Toolkit Troubleshooting
• NVIDIA: Container Toolkit Release Notes
• NVIDIA Container Toolkit GitHub deposu
• NVIDIA: CUDA Toolkit Release Notes
• Docker: dockerd reference (CDI)
• Docker: Install Docker Engine on Ubuntu
• NVIDIA: Container Toolkit Supported Platforms
• NVIDIA: Specialized Configurations with Docker