Como instalar o vLLM no Linux, Windows e macOS

Para instalar o vLLM no Linux com uma GPU NVIDIA, crie um ambiente Python 3.12 limpo e execute pip install vllm, depois inicie um servidor com vllm serve Qwen/Qwen3-8B. Esse é todo o caminho ideal. No Windows, é necessário usar o WSL2 ou o Docker, pois o vLLM publica apenas pacotes binários para Linux; no macOS, é necessário compilar a partir do código-fonte, o que resulta em inferência exclusivamente na CPU.

Antes de instalar: o que o vLLM realmente exige

Requisito	O que funciona
Sistema operacional	Linux (x86_64 é o alvo principal; algumas versões também publicam pacotes binários para aarch64). Windows apenas via WSL2 ou Docker. macOS via compilação a partir do código-fonte.
Python	As versões 3.9–3.12 cobrem as versões lançadas até grande parte de 2025, com suporte à 3.13 adicionado em versões posteriores. A faixa de versões compatíveis muda entre lançamentos — verifique as notas de versão da versão que você instalar.
GPU	GPUs NVIDIA com capacidade de computação 7.0 ou superior (V100, T4, RTX 20-series e posteriores, A10, L4, A100, H100, H200). Placas AMD exigem uma compilação separada com ROCm.
CUDA	Um driver NVIDIA atualizado. O pacote padrão do PyPI inclui o runtime CUDA necessário pela versão do PyTorch embutida nele, portanto você não não precisa instalar o toolkit CUDA do sistema, a menos que compile a partir do código-fonte.
Disco	O próprio pacote tem alguns GB. Os pesos dos modelos predominam — eles são armazenados em ~/.cache/huggingface e variam de poucos GB a centenas de GB.

A lista oficial e continuamente atualizada está na documentação oficial do projeto em docs.vllm.aie as alterações específicas por versão são registradas na página de lançamentos do vLLM. Os pacotes binários publicados e as versões do Python que eles suportam estão listados no PyPI.

Instalar o vLLM no Linux com uma GPU NVIDIA

Opção 1: uv (a mais rápida, e a que agora é recomendada na documentação do vLLM)

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate
uv pip install vllm --torch-backend=auto

O --torch-backend=auto essa flag permite que o uv detecte seu driver e selecione uma versão compatível do PyTorch/CUDA. Se seu driver for mais antigo do que o esperado pelo pacote binário, substitua automático por um backend explícito, como cu126. As versões disponíveis do CUDA mudam a cada lançamento, portanto consulte a página de instalação em vez de presumir que uma determinada tag existe.

Opção 2: pip e venv padrão

python3.12 -m venv ~/vllm-env
source ~/vllm-env/bin/activate
pip install --upgrade pip
pip install vllm

Opção 3: conda

conda create -n vllm python=3.12 -y
conda activate vllm
pip install vllm

Observe que o vLLM deve ser instalado com pip mesmo dentro de um ambiente conda. Não instale o PyTorch separadamente antes disso — o vLLM buscará automaticamente a versão exata do torch com a qual foi compilado.

Verifique a instalação

vllm --version
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
nvidia-smi

Se torch.cuda.is_available() imprime False, pare aqui — o problema está no seu driver ou ambiente, não no vLLM, e nenhum comando serve funcionará até que esse valor retorne True.

Instalar com Docker (a opção mais reprodutível)

O projeto publica uma imagem oficial de servidor compatível com OpenAI. Isso elimina completamente os problemas relacionados ao ambiente Python e é a abordagem recomendada em servidores compartilhados ou de produção:

docker run --runtime nvidia --gpus all 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  --env "HF_TOKEN=$HF_TOKEN" 
  -p 8000:8000 
  --ipc=host 
  vllm/vllm-openai:latest 
  --model Qwen/Qwen3-8B

O --ipc=host o parâmetro é essencial: o vLLM usa memória compartilhada entre processos, e o valor padrão pequeno do Docker /dev/shm causa falhas ao usar paralelismo de tensores. Se você não puder usar o IPC do host, passe --shm-size=8g em vez disso. Montar o cache do Hugging Face significa que cada modelo será baixado apenas uma vez, em vez de uma vez por contêiner. Isso exige que o NVIDIA Container Toolkit esteja instalado no host.

Instalar o vLLM no Windows (WSL2)

O vLLM não possui compilação nativa para Windows. O WSL2 é o caminho suportado e funciona bem:

1. Instale o driver NVIDIA padrão Windows . Não instale um driver de exibição Linux dentro do WSL — a pilha CUDA do WSL mapeia diretamente pelo driver do Windows. A NVIDIA documenta isso na Guia do usuário do CUDA no WSL.
2. No PowerShell: wsl --install -d Ubuntu-24.04, reinicie o sistema se solicitado.
3. Dentro do Ubuntu, execute nvidia-smi. Se sua GPU não for listada, resolva esse problema antes de prosseguir.
4. Instalar python3.12-venv, crie um ambiente virtual (venv) e siga as instruções para Linux acima.

Duas armadilhas específicas do WSL: por padrão, o WSL limita a memória RAM; portanto, adicione uma seção [wsl2] com memory= para C:\Users\\.wslconfig se o carregamento do modelo for interrompido; além disso, os pesos do modelo armazenados no sistema de arquivos do Windows (/mnt/c/...) são carregados de forma notavelmente mais lenta do que os pesos armazenados dentro do sistema de arquivos do WSL.

Instalar o vLLM no macOS

Não há pacote pré-compilado (wheel) para macOS no PyPI. O suporte à Apple Silicon exige uma compilação manual voltada apenas para CPU:

xcode-select --install
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -r requirements/cpu.txt
pip install -e .

O caminho do arquivo de requisitos mudou entre versões (era requirements-cpu.txt nas versões anteriores), portanto verifique a árvore do repositório para a tag que você clonou. Criticamente, essa compilação não utiliza Metal nem a GPU da Apple — a inferência ocorre exclusivamente na CPU e é muito mais lenta do que em uma máquina com CUDA. O objetivo principal de design do vLLM é fornecer alta vazão em servidores com GPUs, o que não corresponde ao cenário típico de um laptop Mac. Se seu objetivo for executar um modelo localmente no macOS, use a rota Ollama ou LM Studio, ambas aproveitando corretamente o Metal.

Linux com GPUs AMD, Intel ou CPU-only

ROCm (AMD), GPUs/XPUs da Intel e CPUs x86 puras possuem seus próprios caminhos de instalação, geralmente envolvendo uma imagem Docker pré-construída ou uma compilação a partir do código-fonte com uma variável de ambiente específica para o dispositivo-alvo, como VLLM_TARGET_DEVICE=cpu. Esses backends evoluem mais rapidamente do que o caminho CUDA, e os comandos exatos mudam entre versões; portanto, consulte sempre a página específica para seu hardware na documentação atual, em vez de copiar comandos de tutoriais.

Iniciar o servidor e testá-lo

vllm serve Qwen/Qwen3-8B 
  --max-model-len 8192 
  --gpu-memory-utilization 0.90 
  --port 8000

Qwen3-8B é um bom primeiro alvo porque não possui restrições de acesso, é baixado rapidamente e cabe em uma única placa de 24 GB no formato bf16. Em seguida, teste:

curl http://localhost:8000/v1/models

curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "Qwen/Qwen3-8B", "messages": [{"role": "user", "content": "Say hi"}]}'

Aviso de segurança: vllm serve inicia sem autenticação. Passe --api-key e mantenha a porta 8000 protegida por um firewall ou proxy reverso — um endpoint vLLM exposto representa uma fatura de inferência ilimitada e aberta em seu próprio hardware.

Parâmetros úteis na primeira execução: --tensor-parallel-size N para distribuir o modelo entre N GPUs, --max-model-len para limitar o contexto (o fator mais eficaz contra estouro de memória na inicialização), --quantization para checkpoints pré-quantizados, --served-model-name para expor um apelido mais curto aos clientes e --enforce-eager para ignorar a captura de gráficos CUDA quando você deseja inicialização mais rápida durante depuração.

O modelo caberá na memória? Dimensione-o antes de instalar

O vLLM carrega os pesos no formato bf16 por padrão, portanto reserve aproximadamente 2 GB de VRAM por bilhão de parâmetros, além do cache KV — e o vLLM aloca esse cache de forma agressiva (90% da placa com o valor padrão --gpu-memory-utilization). Um modelo de 8B ocupa cerca de 16 GB de VRAM no formato bf16. Ao ser quantizado para 4 bits, o mesmo modelo reduz-se a aproximadamente 5 GB, conforme indicado pela tabela Convly banco de dados de modelos:

Modelo	Contexto	~VRAM em 4 bits	Configuração realista em nó único
Qwen3 8B	128K	~5 GB	Uma placa de consumo com 12–24 GB
Llama 3.1 8B	128K	~5 GB	Uma placa de consumo com 12–24 GB
Gemma 3 27B	128K	~16 GB	Uma placa de 24 GB com quantização de 4 bits
Qwen3 32B	128K	~20 GB	Uma placa de 24 GB com quantização de 4 bits, com pouco espaço livre no cache KV
Llama 3.3 70B	128K	~40 GB	2× placas de 24 GB com --tensor-parallel-size 2, ou uma única placa de 48 GB
DeepSeek R1	128K	~400 GB	Servidor multi-GPU, não uma estação de trabalho

Para um valor específico ao seu comprimento de contexto e tamanho de lote, use a Calculadora de VRAM; a análise detalhada por modelo está na Guia de requisitos de VRAM. Se ainda estiver escolhendo hardware, consulte a melhores GPUs para LLMs locais. E, antes de comprar qualquer coisa, vale a pena calcular os custos com a calculadora de autohospedagem versus API — Llama 3.3 70B custa US$ 0,10 para entrada / US$ 0,32 para saída por 1 milhão de tokens em um provedor hospedado, o que é difícil de superar com sua própria eletricidade, a menos que você tenha uma utilização sustentada bastante alta.

Erros comuns de instalação e inicialização do vLLM

Sintoma	Causa e solução
ImportError em vllm._C, ou um erro de ABI/símbolo do torch	O vLLM foi instalado sobre uma versão incompatível do PyTorch. Exclua o ambiente, recrie-o limpo e instale o vLLM primeiro.
“O comprimento máximo de sequência do modelo é maior que o número máximo de tokens que podem ser armazenados no cache KV”	VRAM livre insuficiente para o contexto solicitado. Reduza --max-model-len, aumente --gpu-memory-utilization, ou use um checkpoint quantizado.
CUDA out of memory ao carregar os pesos	Os próprios pesos não cabem na memória. Divida-os com --tensor-parallel-size ou escolha um modelo menor.
Nenhum driver NVIDIA encontrado	Nenhuma GPU visível para o processo. No WSL, o driver deve estar instalado no lado Windows; no Docker, você está faltando --gpus all.
Erro 401/403 ao baixar um modelo	Repositório restrito. Aceite a licença no Hugging Face e, em seguida, autentique-se (hf auth login nas versões atuais da CLI do Hugging Face, huggingface-cli login nas versões mais antigas) ou defina HF_TOKEN.
Pausa longa antes de o servidor aceitar solicitações	Normal: captura e compilação de gráficos CUDA. Use --enforce-eager para ignorá-la durante depuração.

Perguntas frequentes

Posso instalar o vLLM nativamente no Windows?

Não. O vLLM publica apenas wheels para Linux, e pip install vllm no Python para Windows não fornecerá um servidor com GPU funcional. Use o WSL2 com uma distribuição Ubuntu ou execute a imagem oficial do Docker. Ambas são totalmente suportadas e oferecem desempenho próximo ao nativo no mesmo hardware.

Preciso instalar o toolkit CUDA primeiro?

Não é necessário para o wheel padrão. Ele inclui o runtime CUDA por meio da versão fixa do PyTorch, portanto, um driver NVIDIA razoavelmente atual é suficiente. Você só precisa do toolkit completo com nvcc se compilar o vLLM a partir do código-fonte ou criar kernels personalizados.

Como instalo uma versão específica do vLLM ou a compilação noturna (nightly build)?

Fixe-o como qualquer outro pacote: pip install vllm==<versão>, escolhendo entre as versões listadas no PyPI. Wheels noturnos e por commit são publicados separadamente pelo projeto e instalados com uma URL adicional de índice — o endereço atual está documentado na página de instalação, e já mudou anteriormente, portanto consulte-a lá em vez de copiar um comando antigo.

Por que o vLLM ocupa toda a minha GPU?

Por design. Ele pré-aloca um grande pool de blocos de cache KV na inicialização — controlado por --gpu-memory-utilization, cujo valor padrão é 0,9 — porque a atenção paginada é o que garante alto throughput sob concorrência. Reduza esse valor se precisar compartilhar a placa, mas espere um número menor de solicitações simultâneas como consequência.

Devo usar vLLM ou Ollama?

Ollama é um instalador único e multiplataforma voltado para um único usuário em uma única máquina; veja a Guia de instalação do Ollama se isso descreve seu caso. O vLLM é um mecanismo de serviço projetado para suportar muitas solicitações simultâneas por GPU, com processamento contínuo por lote (continuous batching), paralelismo de tensores e uma API compatível com OpenAI. Instale o vLLM quando estiver disponibilizando um aplicativo, não quando estiver conversando localmente.

Qual modelo devo colocar em serviço primeiro?

Comece com algo pequeno e sem restrições, para que você esteja depurando a instalação e não o download — um modelo da classe 8B com cerca de 5 GB em 4 bits é ideal. Assim que o servidor responder a /v1/models, prossiga para modelos maiores. A Ranking de LLMs é uma maneira razoável de pré-selecionar candidatos com base em capacidade, preço e comprimento de contexto antes de comprometer sua VRAM com um modelo específico.