Pinning no Ubuntu e gestão de drivers NVIDIA para servidores de IA

Se é responsável por um servidor de IA do qual outras pessoas dependem, a causa mais provável da sua próxima paragem não é uma avaria de hardware, um bug no modelo ou um incidente elétrico. É um apt-get upgrade que o cliente ou a sua distribuição correram em segundo plano, que trouxe um kernel novo, contra o qual o módulo DKMS da NVIDIA não recompilou de forma limpa, e que deixou o nvidia-smi a devolver Failed to initialize NVML: Driver/library version mismatch no arranque seguinte. É de longe o pedido de apoio mais frequente que a Kentino recebe depois de um servidor estar a funcionar há dois ou três meses.

Este artigo explica como evitar que isso aconteça. Aborda que versão LTS do Ubuntu escolher em meados de 2026, como instalar o driver da NVIDIA de uma forma compreensível, como fixar o driver e o kernel para que uma atualização automática não destrua discretamente toda a stack, e como recuperar quando alguém já o fez.

O destinatário é quem vai escrever sudo numa máquina de 4 ou 8 GPU que é suposto continuar a funcionar durante anos.

Porquê Ubuntu LTS

Há distribuições Linux tecnicamente competentes que não são Ubuntu — Debian stable, RHEL, Rocky, AlmaLinux, openSUSE Leap. Nenhuma delas é uma má escolha e algumas estão até melhor construídas. Ainda assim, recomendamos Ubuntu LTS para servidores de IA, por quatro razões que nada têm a ver com elegância.

A NVIDIA testa primeiro em Ubuntu LTS. Os seus repositórios apt disponibilizam pacotes cuda-keyring explicitamente para ubuntu2204, ubuntu2404e (desde a primavera de 2026) ubuntu2604. O guia de instalação do driver identifica o Ubuntu LTS pelo número de versão; as outras distribuições aparecem no fim do documento.

O ecossistema de contentores assume Ubuntu. Todas as imagens NGC (nvcr.io/nvidia/pytorch, nvcr.io/nvidia/tritonserver, TensorRT-LLM) assentam numa base Ubuntu LTS. A distribuição do anfitrião não tem de coincidir com a do contentor, mas quando coincide os pressupostos de kernel e de userspace encaixam sem atritos.

A maioria das ferramentas de IA de terceiros assume Ubuntu no seu README. vLLM, llama.cpp, SGLang, as instruções de compilação do FlashAttention, os exemplos do Hugging Face Accelerate — tudo escrito e testado primeiro em Ubuntu. O RHEL funciona; mas será o cliente a abrir os issues quando não funcionar.

O conjunto de pessoas que já enfrentaram o seu problema é maior em Ubuntu. Quando o nvidia-smi devolve disparates às 02:00, os três primeiros resultados do Stack Overflow serão específicos de Ubuntu. Isso conta mais do que devia.

O Debian e o RHEL não são más escolhas para um servidor de IA. São é superfícies de teste menores, ciclos de validação da NVIDIA mais lentos e uma comunidade mais pequena quando algo corre mal. Se existe uma razão organizacional forte para uma delas — ambiente isolado FedRAMP, uma licença RHEL já existente, uma equipa de sysadmins habituada a Debian — use-a. Caso contrário, opte por Ubuntu LTS.

22.04 vs 24.04 vs 26.04 em maio de 2026

Há hoje três versões LTS com suporte ativo. A matriz honesta:

Vale a pena destacar alguns pontos desta tabela.

A 22.04 continua a ser a maior base instalada a nível mundial e é aquela sobre a qual a linha de validação da NVIDIA tem mais historial. Se tem um parque de 22.04 a funcionar, não atualize em pânico. Está totalmente suportada até abril de 2027 com atualizações padrão, e o Ubuntu Pro estende a manutenção de segurança até 2032 caso seja necessário. Mas se está a instalar um servidor novo em meados de 2026, está a escolher o sistema operativo para os próximos quatro a cinco anos. À 22.04 resta apenas um ano de suporte padrão. Não comece por aí.

A 24.04 é o ponto ideal para trabalho de IA em produção em 2026. Teve dois anos de correções e de revisões de kernel HWE, todos os ramos de driver da NVIDIA a partir do R535 tiveram pacotes de qualidade de produção no repositório ubuntu2404 da NVIDIA, todas as imagens NGC indicam a 24.04 como base suportada, e só em abril de 2029 termina o suporte padrão. É isto que instalamos hoje nas máquinas Kentino novas.

A 26.04 acabou de sair. Traz o R595 como driver predefinido no repositório oficial do Ubuntu, inclui CUDA nos repositórios principais pela primeira vez e tem boas melhorias na relação Wayland / NVIDIA, que interessam a desktops e nada a servidores de inferência sem ecrã. O risco para um servidor de IA é o calendário: nos primeiros três a quatro meses depois de uma versão .0 LTS, as recomendações do ubuntu-drivers e o comportamento dos módulos DKMS ainda andam a mudar, e o próprio repositório da NVIDIA leva alguns ciclos a validar plenamente cada ramo de driver contra o novo kernel. O padrão das versões LTS anteriores (20.04, 22.04, 24.04) mostra que a primeira versão intermédia — 26.04.1 em agosto de 2026 — é o momento em que as instalações de produção começam a fazer sentido. Se puder esperar, espere. Se não puder, faça um teste de resistência de duas semanas antes de lá pôr seja o que for de importante.

Os caminhos de instalação do driver

Há três formas de instalar o driver da NVIDIA numa máquina Ubuntu. Não são igualmente boas.

ubuntu-drivers install é o caminho fácil. A Canonical mantém uma ferramenta que analisa o hardware, escolhe o ramo de driver que considera recomendado e instala o pacote correspondente do repositório Ubuntu. Trata da assinatura para Secure Boot (com a chave da Canonical), conhece os kernels HWE e, num desktop com uma única GPU de consumo, funciona bem. Num servidor de IA é o caminho frágil: o ramo recomendado pode mudar entre versões do pacote ubuntu-drivers-common — a versão que recebe num apt update depende do que o Ubuntu empacotou nessa semana, e tem menos controlo sobre a versão menor exata do driver que fica em disco. Use-o no portátil. Não o use no servidor.

apt a partir do repositório CUDA da NVIDIA é o caminho manual, mas controlável. Adiciona o pacote cuda-keyring da NVIDIA, que configura a fonte apt correta para a sua versão de Ubuntu, e depois instala exatamente os pacotes que quer — cuda-drivers-580, nvidia-driver-580, nvidia-dkms-580, sem surpresas. A NVIDIA controla o empacotamento, o cliente controla a versão. É esta a predefinição da Kentino.

O instalador .run obtido em developer.nvidia.com escreve ficheiros em /usr/local, gere as suas próprias recompilações do módulo de kernel e não se integra com o apt de todo. É a resposta certa em dois casos muito específicos: hardware acabado de sair, cujo ramo de driver ainda não chegou ao repositório apt — ou uma estação de trabalho onde se está ativamente a desenvolver ou a depurar o driver. Fora isso, é a resposta errada. Entra em conflito com o DKMS, não é abrangido pelo apt-mark hold, e parte-se silenciosamente na próxima atualização do kernel, porque a recompilação passou a ser manual.

Em concreto, num servidor 24.04 acabado de instalar, a sequência predefinida da Kentino é:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

# Instale o ramo do driver que realmente quer, indicando o número.
sudo apt install -y cuda-drivers-580 nvidia-dkms-580
sudo reboot

Depois do reinício, o nvidia-smi deve indicar o driver 580.x e a versão máxima de CUDA que o driver suporta (CUDA 13 para o R580). A instalação é só isto. Repare no que não está lá: nenhum cuda meta-pacote, nenhum cuda-toolkit-13-0 (só necessário se compilar código CUDA no anfitrião — ver L02), nenhum ubuntu-drivers. Escolheu a versão, instalou a versão, sabe o que está em disco.

Os ramos de driver que contam em 2026

A NVIDIA disponibiliza os seus drivers Linux em ramos com janelas de suporte próprias. A meio de 2026:

O R580 é a predefinição certa em 2026. Suporta todas as GPU da gama Kentino (5090, 4090, RTX Pro 6000 Blackwell em ambas as edições, L40, L4), incluindo a capacidade de computação sm_120 da arquitetura Blackwell, e traz suporte nativo para CUDA 13 — que é o alvo de todas as versões recentes do vLLM, do PyTorch 2.10/2.11 e do TensorRT-LLM. O R570 é a escolha LTSB conservadora para quem tem um parque de Ada (4090 / L40 / L4) que não precisa das funcionalidades mais recentes e quer adiar por mais um ano a transição de ramo. O R595 é o que o Ubuntu 26.04 traz por omissão e o que convém para o hardware mais recente de todos; num servidor que só corre o que hoje existe na gama Kentino, o R580 é mais conservador e tem as mesmas funcionalidades.

A dança das três versões: driver / CUDA / PyTorch

Três versões independentes têm de estar alinhadas. Assentam umas sobre as outras assim:

Wheel do PyTorch (p. ex. torch==2.11.0+cu130)
        │  traz o seu próprio runtime CUDA, cuDNN e NCCL dentro do wheel
        ▼
Versão do runtime CUDA (aqui: 13.0)
        │  o driver tem de suportar esta versão de CUDA ou mais recente
        ▼
Ramo do driver NVIDIA (aqui: R580 → suporta CUDA 13.x)

A regra é que o driver suporta uma versão máxima de runtime CUDA. Tudo o que for mais antigo do que esse máximo, dentro da mesma versão principal, funciona. Assim, o R580 (máximo CUDA 13.x) corre wheels do PyTorch compilados contra 13.0, 13.1 e 13.2; já não corre wheels compilados contra o (hipotético) CUDA 14.0 enquanto não mudar de ramo de driver. Drivers mais antigos não conseguem correr CUDA mais recente — existe compatibilidade futura para algumas placas de centro de dados, mas é frágil e não é assim que convém trabalhar.

Mapa prático do que os servidores Kentino correm hoje:

A sua tarefa é fixar o driver e deixar que tudo o que está acima dele acompanhe. Nem sequer precisa de instalar CUDA no anfitrião se servir tudo a partir de contentores (e deve fazê-lo — ver L02). O anfitrião precisa do driver e do toolkit de contentores. Mais nada.

Fixar versões — o comando mais valioso deste artigo

Assim que o driver estiver instalado e o nvidia-smi estiver satisfeito, fixe-o. Fixar significa dizer ao apt que não atualize, não reverta nem remova determinados pacotes, mesmo que uma dependência ou uma atualização de segurança lhes fossem mexer. O comando é apt-mark hold.

# Fixe o ramo do driver.
sudo apt-mark hold \
  cuda-drivers \
  cuda-drivers-580 \
  nvidia-driver-580 \
  nvidia-driver-580-server \
  nvidia-dkms-580 \
  libnvidia-compute-580 \
  libnvidia-compute-580-server

# Fixe o kernel em execução e os seus headers — o DKMS precisa de ambos para recompilar,
# e um salto de kernel que o DKMS não consiga tratar é exatamente como se perde a GPU.
RUNNING=$(uname -r)
sudo apt-mark hold "linux-image-${RUNNING}" "linux-headers-${RUNNING}"

# Se estiver a usar o meta-pacote do kernel HWE do Ubuntu, fixe-o também:
sudo apt-mark hold linux-generic-hwe-24.04 linux-image-generic-hwe-24.04 linux-headers-generic-hwe-24.04

# Verifique.
apt-mark showhold

Isto resolve cerca de metade de todos os pedidos de apoio do tipo "o meu servidor de IA deixou de funcionar". Quando o apt update && apt upgrade corre — manualmente, a partir de uma ferramenta de gestão de configuração ou sob o unattended-upgrades — esses pacotes fixados não se mexem. Aparecem listados como "kept back" no resultado da atualização, e podem ser revistos e libertados deliberadamente numa janela de manutenção, quando o cliente entender.

Algumas armadilhas. Há quem fixe o nvidia-driver-580 e se esqueça do cuda-drivers-580, que é o verdadeiro meta-pacote do repositório CUDA. Se o cuda-drivers-580 for atualizado porque uma dependência transitiva quer uma versão mais recente, arrasta consigo um novo nvidia-dkms-580 e lá se foi a fixação. Liste os dois. Há também quem fixe a imagem do kernel mas não os headers: o kernel atualiza-se na mesma por causa de um meta-pacote e o DKMS não encontra os headers quando tenta recompilar — o nvidia-smi funciona até ao reinício e depois deixa de funcionar. Fixe sempre a imagem e os headers em conjunto.

As armadilhas do kernel e do DKMS

O DKMS (Dynamic Kernel Module Support) é o sistema que recompila módulos de kernel externos sempre que o kernel muda. O pacote nvidia-dkms-XXX da NVIDIA regista o driver como módulo DKMS para que, em teoria, uma atualização de kernel gerida pelo apt desencadeie uma recompilação limpa do módulo e o sistema arranque a funcionar.

Na prática, as recompilações do DKMS falham de três formas recorrentes:

Os headers do kernel não estão instalados para o novo kernel — algo comum quando o pacote do kernel foi instalado mas o dos headers foi filtrado por uma regra de preferências do apt ou por uma seleção personalizada. O novo kernel arranca, falta o módulo da NVIDIA e o nvidia-smi devolve "NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver."

O novo kernel é demasiado recente para o ramo do driver. O R570 não compila de forma limpa contra o kernel 6.14 mais recente; o R580 compila. Se deixar que um salto HWE o leve para um kernel contra o qual o ramo do driver nunca foi testado, o DKMS produz um erro de compilação em /var/lib/dkms/nvidia/.../make.log e o sistema reinicia a funcionar, mas sem GPU.

O Secure Boot está ativo e o módulo recompilado não está assinado. Os pacotes instalados pelo ubuntu-driversda Canonical já trazem a assinatura tratada. Os pacotes do repositório CUDA da NVIDIA não; exigem que se registe uma Machine Owner Key (MOK) e se assinem os módulos recompilados a cada mudança de kernel. O DKMS consegue assinar automaticamente com a configuração certa por módulo, mas isso tem de ser preparado antes da primeira recompilação, não depois de o sistema deixar de arrancar. Se não precisa de Secure Boot — e num servidor de inferência sem ecrã, dentro de um rack fechado, é discutível que precise — desative-o no firmware antes de instalar o driver e elimine de uma vez toda esta classe de problemas.

Fixar o kernel contorna as três situações. O kernel não muda sem a sua intervenção, os headers mantêm-se emparelhados e o módulo recompilado continua a carregar. Quando quiser mesmo passar a um kernel novo — por causa de um CVE ou de uma funcionalidade real — fá-lo deliberadamente, com um snapshot e pronto a reverter.

CUDA em bare-metal — quando (raramente) ainda faz sentido

L02 defende que o CUDA em bare-metal é hoje, na maior parte dos casos, a escolha errada: os contentores escondem a dança das versões de CUDA, separam o anfitrião da carga de trabalho e impõem um custo de desempenho negligenciável. Isso é verdade em ~95% das instalações.

As exceções são poucas. Análise de desempenho de GPU ao nível do kernel com o Nsight Systems / Nsight Compute, em que a camada do contentor esconde as chamadas de sistema que interessam. Trabalho sobre o driver — correr drivers pré-lançamento da NVIDIA, depurar falhas que envolvem o próprio módulo de kernel. Ambientes rigorosamente isolados da rede, em que obter e confiar em imagens OCI é mais difícil do que manter um espelho apt congelado. E um punhado de instalações de HPC que construíram tudo à volta do module load e de MPI em bare-metal e não têm interesse em mudar.

Para todos os outros: instale o driver em bare-metal, deixe o anfitrião sem CUDA e corra o CUDA dentro de contentores. O nvidia-container-toolkit (abordado em L02) faz a ponte entre os dois sem atritos.

Atualizações automáticas — o que permitir e o que bloquear

O pacote unattended-upgrades do Ubuntu é bom e deve ser mantido ativo. Prescindir por completo das atualizações de segurança num servidor ligado à rede é pior do que o risco de uma atualização automática correr mal. O padrão certo é: atualizações de segurança sim, pacotes de kernel e da NVIDIA não.

Edite o /etc/apt/apt.conf.d/50unattended-upgrades e acrescente ao bloco de lista negra:

Unattended-Upgrade::Package-Blacklist {
    "linux-image-";
    "linux-headers-";
    "linux-generic";
    "linux-modules-";
    "nvidia-";
    "libnvidia-";
    "cuda";
    "cuda-";
    "libcudnn";
};

apt-mark hold já impede estes pacotes de serem atualizados. A lista negra é cinto e suspensórios — torna a intenção explícita, impede o unattended-upgrades de sequer registar uma tentativa e sobrevive a um descuidado apt-mark unhold por parte de um administrador menos experiente. Use as duas coisas.

Confirme acompanhando o /var/log/unattended-upgrades/unattended-upgrades.log depois da execução seguinte. Deve ver os pacotes de segurança a passar e os fixados / em lista negra a serem explicitamente ignorados.

O manual de recuperação do "fiz dist-upgrade e agora nada funciona"

Alguém correu apt full-upgrade (ou foi a ferramenta de gestão de configuração) e, no reinício seguinte, as GPU desapareceram. Ordem das operações:

1. Arranque. Se o sistema não arrancar, mantenha shift / Esc premido no GRUB e escolha o kernel anterior no menu de arranque. Confirme que o nvidia-smi funciona com o kernel antigo. Se funcionar, o problema é o kernel novo; fixe o antigo (apt-mark hold linux-image-<old>) e prossiga.
2. Se o sistema arrancou mas o nvidia-smi indica uma incompatibilidade de NVML, está a correr userspace novo contra um módulo antigo já carregado. Reinicie. Quase sempre resolve.
3. Se o nvidia-smi indicar que o driver não está carregado, verifique o /var/lib/dkms/nvidia/<version>/build/make.log e o dmesg | grep -i nvidia. As falhas mais comuns: headers do kernel em falta (apt install linux-headers-$(uname -r) e depois dkms autoinstall); um kernel demasiado recente para o driver (reverta o kernel ou mude deliberadamente de ramo de driver); o Secure Boot a rejeitar o módulo não assinado (mokutil --sb-state, e depois desative o SB ou registe uma MOK).
4. Se foram os próprios pacotes do driver que ficaram num estado indesejado depois de um dist-upgrade — por exemplo, o meta-pacote trouxe o R585 por cima do R580 fixado porque alguém removeu a fixação — limpe e reinstale: sudo apt purge '*nvidia*' '*cuda*' && sudo apt autoremove, depois repita a instalação a partir do repositório CUDA na versão que realmente quer e volte a aplicar as fixações.
5. Se tiver um snapshot — e deve ter, veja abaixo — restaure-o. São vinte minutos até voltar a um estado bom conhecido, contra quatro horas de depuração.

Faça um snapshot antes de mexer no driver ou no kernel

Seja qual for o esquema de armazenamento, faça um snapshot antes de qualquer operação sobre o driver ou o kernel. Quem usa ZFS (/ em ZFS ou num dataset separado) tem isto de graça com zfs snapshot rpool@pre-driver-upgrade-2026-05-15. Quem usa LVM com thin pools pode recorrer a lvcreate --snapshot. Quem usa ext4 sem LVM fica limitado a cópias de segurança completas; é uma das razões por que abordamos o esquema de sistema de ficheiros em L04.

A disciplina que compensa: nunca mexer no driver, nos pacotes CUDA ou no kernel sem ter feito um snapshot nos cinco minutos anteriores. Um snapshot custa segundos. Não ter um quando uma atualização corre mal custa meio dia de paragem e o serão de alguém.

Caminho de atualização entre versões LTS

As atualizações de LTS para LTS do Ubuntu acontecem de dois em dois anos; em servidores de IA recomendamos saltar uma sim, uma não. O caminho é:

22.04  ──(saltar a interim 23.x, saltar a 24.04 se estável em produção)──▶  26.04
24.04  ──(saltar a interim 25.x, saltar a 26.04 se estável em produção)──▶  28.04

A razão: o custo de uma atualização LTS num servidor de IA é elevado (revalidação do driver, novo teste das imagens de contentor, muitas vezes uma nova ronda de benchmarks de integração), o benefício de dar um passo em vez de dois é pequeno, e as ferramentas de atualização LTS para LTS do Ubuntu suportam plenamente o salto. Planeie a atualização, agende uma janela de manutenção, faça um snapshot, corra do-release-upgrade, faça um teste de resistência durante uma semana e só depois devolva as cargas de trabalho. Passar diretamente de 22.04 para 26.04 é suportado e é o que a maioria dos clientes Kentino acabará por fazer no final de 2026 ou em 2027.

O que evitar: atualizações no local durante um sprint de desenvolvimento, atualizar sem snapshot, e atualizar fazendo ao mesmo tempo o dist-upgrade da stack da NVIDIA. Mude uma coisa de cada vez.

---

Este artigo faz parte da Kentino Wiki, uma série de referência sobre computação de IA, robótica e os sistemas que os ligam. Comentários e correções são bem-vindos em info@kentino.com.