# Docker NVIDIA Container Toolkit Kurulumu: Ubuntu 22.04, 24.04 ve 26.04 - Adres: https://gpukiralama.com.tr/blog/docker-nvidia-container-toolkit-kurulum/ - Kategori: Teknik - Yayın: 2026-10-24 · Son güncelleme: 2026-10-31 NVIDIA Container Toolkit kurulumu dört adımdır: sürücüyü doğrulayın, NVIDIA'nın apt deposundan nvidia-container-toolkit paketini kurun, nvidia-ctk ile Docker'ı yapılandırıp yeniden başlatın ve docker run --rm --gpus all ubuntu nvidia-smi ile test edin. Sunucuya CUDA Toolkit kurmanız gerekmez. CDI, rootless Docker, Podman ve sık hataların çözümleri de rehberde. ## 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. ```bash 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](/blog/pytorch-gpu-kurulum-rehberi/) 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 sürümü | Karşılık gelen sürücü dalı | |---|---| | 13.0 | R580 | | 13.1 | R590 | | 13.2 | R595 | | 13.3 | R610 | | 13.4 | R615 | 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ı: ```bash 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: ```bash 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: ```json { "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: ```bash 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: ```bash 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](/blog/docker-gpu-kullanim-rehberi/) 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](/blog/video-transcoding-gpu-rehberi/)). 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](/blog/jupyter-bulut-gpu-rehberi/). ## 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. ```bash 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: ```bash 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: | Motor | Yapılandırma | GPU isteme | Not | |---|---|---|---| | Docker | `nvidia-ctk runtime configure --runtime=docker` | `--gpus all` | En yaygın kullanım | | Docker (CDI) | Docker 28.3.0 ve sonrasında ek adım yok | `--device nvidia.com/gpu=all` | `daemon-reload` sonrası erişim kaybı yaşanmaz | | Rootless Docker | Yukarıdaki üç komut | `--gpus all` | Kullanıcıya ait daemon.json | | Podman | Ek adım yok, CDI tanımı yeterli | `--device nvidia.com/gpu=all` | Podman 4.1.0 ve sonrası | | containerd (Kubernetes) | `nvidia-ctk runtime configure --runtime=containerd` | Kubernetes cihaz eklentisi | Kümelerde NVIDIA GPU Operator'e bakın | | nerdctl | Ek adım yok | `--gpus=all` | Root'lu ve root'suz çalışır | | CRI-O | `nvidia-ctk runtime configure --runtime=crio` | Kubernetes cihaz eklentisi | Ayar ek bir dosyaya yazılır | 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: ```bash 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: | Hata | Nedeni | Çözüm | |---|---|---| | `could not select device driver "" with capabilities: [[gpu]]` | Toolkit kurulu değil ya da Docker kurulumdan sonra yeniden başlatılmadı | Kurulum ve yapılandırma adımlarını tamamlayıp Docker'ı yeniden başlatın | | `apt-get update` sırasında `Conflicting values set for option Signed-By` | Eski kurulumlardan kalan ve aynı depoyu gösteren liste dosyaları (`nvidia-docker.list` gibi) | Aşağıdaki komutla bulup silin | | Çalışan konteynerde `Failed to initialize NVML: Unknown Error` | systemd cgroup sürücüsü ve `systemctl daemon-reload` | Konteyneri yeniden oluşturun; kalıcı çözüm için CDI kullanın ya da daemon.json'a `"exec-opts": ["native.cgroupdriver=cgroupfs"]` ekleyin | | `unsatisfied condition: cuda>=...` | Sürücü, imajın CUDA sürümü için eski | Sürücüyü güncelleyin ya da daha düşük CUDA etiketli bir imaj seçin | | `groups: cannot find name for group ID ...` | Yalnızca görsel bir uyarı | Yok sayabilirsiniz; cihaz erişimini etkilemez | ### "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: ```bash 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: ```bash 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](/gpu-modelleri/nvidia-rtx-pro-4000/) (24 GB, aylık $450), [7–14B parametreli modellerle](/araclar/vram-hesaplayici/) çalışan servisler için [L40S](/gpu-modelleri/nvidia-l40s/) (48 GB, aylık $900) iyi başlangıç noktalarıdır. Tek siparişte [en fazla 8 GPU](/blog/multi-gpu-egitim-rehberi/) alabilirsiniz. İş yüküne göre önerdiğimiz kartları [hizmetler sayfamızda](/hizmetler/) bulabilirsiniz. vLLM ya da SGLang'in hazır Docker imajlarıyla model sunacaksanız GPU ve bellek seçimini [LLM inference sayfamızda](/hizmetler/inference/) 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](/fiyatlandirma/). 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) - [NVIDIA: Support for Container Device Interface](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html) - [NVIDIA: Container Toolkit Troubleshooting](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/troubleshooting.html) - [NVIDIA: Container Toolkit Release Notes](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/release-notes.html) - [NVIDIA Container Toolkit GitHub deposu](https://github.com/NVIDIA/nvidia-container-toolkit) - [NVIDIA: CUDA Toolkit Release Notes](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html) - [Docker: dockerd reference (CDI)](https://docs.docker.com/reference/cli/dockerd/) - [Docker: Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) - [NVIDIA: Container Toolkit Supported Platforms](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/supported-platforms.html) - [NVIDIA: Specialized Configurations with Docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html) ## Sık sorulan sorular **NVIDIA Container Toolkit olmadan Docker'da GPU kullanılabilir mi?** Hayır. Docker GPU'yu konteynere tek başına veremez; toolkit, konteyner başlarken sürücü kütüphanelerini ve GPU cihaz dosyalarını içeri bağlar. Ana makinede bunun dışında yalnızca NVIDIA sürücüsü gerekir, CUDA Toolkit gerekmez. **nvidia-docker veya nvidia-docker2 kurmam gerekir mi?** Hayır. nvidia-docker ve nvidia-docker2 kullanımdan kalktı; işlevleri nvidia-container-toolkit paketine taşındı. Güncel kurulumda toolkit paketlerini kurup Docker'ı nvidia-ctk ile yapılandırmanız yeterlidir. **--gpus ile --device nvidia.com/gpu=all arasındaki fark nedir?** --gpus, Docker'ın NVIDIA desteğini kullanan klasik yoldur. --device nvidia.com/gpu=all ise CDI standardıyla çalışır; Docker 28.3.0 ve sonrasında varsayılan olarak açıktır ve systemctl daemon-reload sonrasında GPU erişiminin kaybolması sorununu yaşamaz. **NVIDIA Container Toolkit nasıl güncellenir?** nvidia-container-toolkit, nvidia-container-toolkit-base, libnvidia-container-tools ve libnvidia-container1 paketlerini aynı sürüme birlikte güncelleyin. Toolkit 1.18'den beri bu paketlerin sürümlerinin birebir aynı olması gerekiyor. **Konteynerdeki CUDA sürümü sunucudaki sürücüden yeni olabilir mi?** Belli bir sınıra kadar evet: CUDA 13.x uygulamaları alt sürüm uyumluluğu sayesinde 580 ve üzeri sürücülerde çalışır. Sürücü, imajın istediği CUDA sürümü için fazla eskiyse konteyner 'unsatisfied condition: cuda>=...' hatasıyla başlamaz. **Kubernetes'te de aynı adımlar mı uygulanır?** Paket kurulumu aynıdır; containerd için yapılandırma komutu nvidia-ctk runtime configure --runtime=containerd olur ve ardından containerd yeniden başlatılır. Kubernetes kümeleri için NVIDIA ayrıca GPU Operator'ü sunar. **NVIDIA Container Toolkit hangi Ubuntu sürümlerinde çalışır?** NVIDIA'nın test ettiği Ubuntu sürümleri arasında 22.04, 24.04 ve 26.04 var; kurulum adımları üçünde de aynıdır. Docker Engine'i Ubuntu'nun docker.io paketinden değil, Docker'ın resmi apt deposundan kurun. **NVIDIA Container Toolkit nasıl kaldırılır?** nvidia-container-toolkit, nvidia-container-toolkit-base, libnvidia-container-tools ve libnvidia-container1 paketlerini sudo apt-get purge ile kaldırın. Ardından /etc/docker/daemon.json dosyasından nvidia çalışma zamanı bloğunu (varsa "default-runtime": "nvidia" satırını da) silip Docker'ı yeniden başlatın.