Come installare vLLM su Linux, Windows e macOS

Per installare vLLM su Linux con una GPU NVIDIA, crea un ambiente Python 3.12 pulito ed esegui pip install vllm, quindi avvia un server con vllm serve Qwen/Qwen3-8B. Questo è l'intero percorso felice. Windows richiede WSL2 o Docker perché vLLM pubblica solo wheel per Linux, e macOS richiede una build da sorgente che esegue inferenza solo su CPU.

Prima di installare: cosa richiede effettivamente vLLM

Requisito	Cosa funziona
Sistema operativo	Linux (x86_64 è il target primario; alcune versioni pubblicano anche wheel aarch64). Windows solo via WSL2 o Docker. macOS via build da sorgente.
Python	3.9–3.12 copre le release fino a gran parte del 2025, con 3.13 aggiunto nelle versioni successive. L'intervallo supportato cambia tra le release — controlla le note di rilascio per la versione che installi.
GPU	GPU NVIDIA con compute capability 7.0 o superiore (V100, T4, RTX 20-series e più recenti, A10, L4, A100, H100, H200). Le schede AMD necessitano della build separata ROCm.
CUDA	Un driver NVIDIA attuale. Il wheel predefinito di PyPI include il runtime CUDA di cui la sua build PyTorch in bundle ha bisogno, quindi non non hai bisogno di un toolkit CUDA di sistema a meno che tu non compili da sorgente.
Disco	Il pacchetto stesso è pochi GB. I pesi del modello dominano — si trovano in ~/.cache/huggingface e variano da pochi GB a centinaia di GB.

L'elenco autorevole e continuamente aggiornato si trova nella documentazione del progetto stesso su docs.vllm.aie le modifiche specifiche della versione sono registrate nella pagina delle release di vLLM. Le wheel pubblicate e le versioni di Python supportate sono elencate su PyPI.

Installare vLLM su Linux con una GPU NVIDIA

Opzione 1: uv (più veloce e quello che la documentazione di vLLM consiglia ora)

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

Il --torch-backend=auto consente a uv di rilevare il tuo driver e selezionare una build PyTorch/CUDA corrispondente. Se il tuo driver è più vecchio di quanto la wheel si aspetti, sostituisci auto con un backend esplicito come cu126. Quali build CUDA sono disponibili cambia con ogni release, quindi consulta la pagina di installazione invece di assumere che un tag specifico esista.

Opzione 2: pip e venv semplici

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

Opzione 3: conda

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

Nota che vLLM dovrebbe essere installato con pip anche all'interno di un ambiente conda. Non installare PyTorch separatamente prima — vLLM estrarrà la build torch esatta con cui è stato compilato.

Verifica l'installazione

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

Se torch.cuda.is_available() stampa False, fermati qui — il problema è il tuo driver o ambiente, non vLLM, e nessun comando serve funzionerà finché questo non leggerà True.

Installare con Docker (l'opzione più riproducibile)

Il progetto pubblica un'immagine server ufficiale compatibile con OpenAI. Questo evita completamente i problemi dell'ambiente Python ed è il percorso da seguire su una macchina condivisa o di produzione:

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

Il --ipc=host è importante: vLLM usa memoria condivisa tra i processi e il default piccolo di Docker /dev/shm causa crash con il parallelismo dei tensor. Se non puoi usare host IPC, passa --shm-size=8g invece. Montare la cache di Hugging Face significa che scarichi ogni modello una volta invece che una volta per container. Questo richiede NVIDIA Container Toolkit sull'host.

Installare vLLM su Windows (WSL2)

vLLM non ha una build nativa per Windows. WSL2 è il percorso supportato e funziona bene:

1. Installa il driver NVIDIA standard Windows . Non installare un driver display Linux all'interno di WSL — lo stack CUDA di WSL si mappa attraverso il driver Windows. NVIDIA documenta questo nella guida utente CUDA on WSL.
2. In PowerShell: wsl --install -d Ubuntu-24.04, quindi riavvia se richiesto.
3. All'interno di Ubuntu, esegui nvidia-smi. Se la tua GPU non è elencata, risolvilo prima di continuare.
4. Installa python3.12-venv, crea un venv e segui le istruzioni Linux sopra.

Due gotcha specifici di WSL: WSL limita la RAM per impostazione predefinita, quindi aggiungi una [wsl2] sezione con memory= a C:Users.wslconfig se il caricamento del modello viene interrotto; e i pesi del modello archiviati nel filesystem Windows («/mnt/c/...«») si caricano notevolmente più lentamente rispetto ai pesi all'interno del filesystem WSL.

Installare vLLM su macOS

Non c'è alcuna wheel macOS su PyPI. Il supporto per Apple silicon è una build da codice sorgente solo CPU:

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

Il percorso del file dei requisiti è cambiato tra le versioni (era requirements-cpu.txt nelle release precedenti), quindi controlla l'albero del repository per il tag che estrai. Crucialmente, questa build non usa Metal o la GPU di Apple — l'inference gira su CPU ed è molto più lenta di una macchina CUDA. L'obiettivo di design di vLLM è il serving in batch ad alta velocità su GPU server, che non è quello che un laptop Mac è. Se il tuo obiettivo è eseguire un modello localmente su macOS, usa la Ollama rotta o LM Studio, che usano entrambi Metal correttamente.

AMD, Intel e Linux solo CPU

ROCm (AMD), Intel GPU/XPU e x86 solo CPU hanno tutti i loro percorsi di installazione specifici, generalmente o un'immagine Docker precostruita o una build da codice sorgente con una variabile d'ambiente device-target come VLLM_TARGET_DEVICE=cpu. Questi backend evolvono più rapidamente rispetto alla versione CUDA e i comandi esatti cambiano tra le release: consulta quindi sempre la pagina dedicata al tuo hardware nella documentazione corrente, anziché copiare comandi da tutorial obsoleti.

Avvia il server e testalo

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

Qwen3-8B è un buon primo modello da provare perché non è soggetto a restrizioni, si scarica rapidamente ed entra comodamente su una singola GPU da 24 GB in formato bf16. Prova quindi:

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"}]}'

Nota di sicurezza: vllm serve parte senza autenticazione. Specifica --api-key e mantieni la porta 8000 protetta da firewall o reverse proxy: esporre un endpoint vLLM significa lasciare aperto, senza limitazioni, un canale di inferenza sul tuo hardware.

Opzioni utili da usare al primo avvio: --tensor-parallel-size N per suddividere il carico su N GPU, --max-model-len per limitare la lunghezza massima del contesto (il singolo parametro più efficace contro gli OOM all’avvio), --quantization per checkpoint già quantizzati, --served-model-name per esporre un alias più breve ai client e --enforce-eager per saltare la cattura dei CUDA graph quando desideri un avvio più rapido durante il debugging.

Il modello si adatterà? Dimensionalo prima di installare

vLLM carica i pesi in formato bf16 per impostazione predefinita, quindi prevedi circa 2 GB di VRAM per miliardo di parametri, più la cache KV — e vLLM prealloca tale cache in modo aggressivo (fino al 90% della GPU con il valore predefinito --gpu-memory-utilization). Un modello da 8 miliardi di parametri occupa circa 16 GB di VRAM in bf16. Quantizzato a 4 bit, lo stesso modello scende a circa 5 GB, secondo quanto indicato da Convly database di modelli:

Modello	Contesto	~VRAM a 4 bit	Configurazione realistica su singolo nodo
Qwen3 8B	128K	~5 GB	Una GPU consumer da 12–24 GB
Llama 3.1 8B	128K	~5 GB	Una GPU consumer da 12–24 GB
Gemma 3 27B	128K	~16 GB	Una scheda da 24 GB a 4 bit
Qwen3 32B	128K	~20 GB	Una scheda da 24 GB a 4 bit, con spazio limitato nella cache KV
Llama 3.3 70B	128K	~40 GB	2× 24 GB con --tensor-parallel-size 2, oppure una singola scheda da 48 GB
DeepSeek R1	128K	~400 GB	Server multi-GPU, non una workstation

Per un valore specifico per la vostra lunghezza di contesto e dimensione del batch, utilizzate il Calcolatore VRAM; l'analisi completa per modello è disponibile nel Guida ai requisiti di VRAM. Se state ancora scegliendo l'hardware, consultate il migliori GPU per LLM locali. E prima di acquistare qualsiasi cosa, vale la pena calcolare i costi con il calcolatore self-hosting vs API — Llama 3.3 70B costa $0,10 in ingresso / $0,32 in uscita per ogni milione di token presso un fornitore ospitato, un prezzo difficile da battere autonomamente con l'elettricità, a meno che non si raggiunga un'utilizzo sostenuto piuttosto elevato.

Errori comuni di installazione e avvio di vLLM

Sintomo	Causa e soluzione
ImportError su vllm._C, oppure un errore ABI/simbolo da torch	vLLM è stato installato su una versione di PyTorch incompatibile. Eliminate l'ambiente, ricreatelo da zero e installate vLLM per primo.
«La lunghezza massima della sequenza del modello è superiore al numero massimo di token che possono essere memorizzati nella cache KV»	Non c'è abbastanza VRAM libera per il contesto richiesto. Riducete --max-model-len, aumentate --gpu-memory-utilization, oppure utilizzate un checkpoint quantizzato.
Memoria CUDA esaurita durante il caricamento dei pesi	I pesi stessi non entrano nella memoria disponibile. Suddivideteli con --tensor-parallel-size oppure scegliete un modello più piccolo.
Nessun driver NVIDIA rilevato	Nessuna GPU visibile al processo. In WSL, il driver deve essere installato sul lato Windows; in Docker, manca l'opzione --gpus all.
Errore 401/403 durante il download di un modello	Repository protetto. Accettate la licenza su Hugging Face, quindi autenticatevi (hf auth login nelle versioni correnti della CLI di Hugging Face, huggingface-cli login nelle versioni precedenti) oppure impostate HF_TOKEN.
Lunga pausa prima che il server accetti le richieste	Comportamento normale: acquisizione e compilazione dei grafi CUDA. Usate --enforce-eager per saltarla durante il debugging.

Domande frequenti

Posso installare vLLM nativamente su Windows?

No. vLLM pubblica wheel solo per Linux e pip install vllm in Python su Windows non vi fornirà un server GPU funzionante. Utilizzate WSL2 con una distribuzione Ubuntu oppure eseguite l'immagine Docker ufficiale. Entrambe le soluzioni sono pienamente supportate e offrono prestazioni quasi native sullo stesso hardware.

Devo installare il toolkit CUDA prima?

Non necessario per il wheel predefinito. Quest'ultimo include il runtime CUDA tramite la versione di PyTorch fissata, quindi è sufficiente un driver NVIDIA ragionevolmente aggiornato. È invece necessario installare l'intero toolkit CUDA con nvcc solo se compilate vLLM da sorgente o create kernel personalizzati.

Come installo una versione specifica di vLLM o la build nightly?

Fissatelo come qualsiasi altro pacchetto: pip install vllm==<versione>, scegliendo tra le versioni elencate su PyPI. I wheel nightly e quelli relativi a ogni commit vengono pubblicati separatamente dal progetto e installati specificando un URL aggiuntivo per l'indice — l'indirizzo corrente è documentato nella pagina di installazione, ed è già cambiato in passato, quindi consultatela direttamente anziché copiare un comando obsoleto.

Perché vLLM occupa tutta la mia GPU?

È un comportamento previsto. All'avvio viene preallocato un ampio pool di blocchi per la cache KV — controllato da --gpu-memory-utilization, il cui valore predefinito è 0,9 — perché l'attenzione paginata è ciò che consente elevate prestazioni in termini di throughput sotto carico concorrente. Riducete questo valore se dovete condividere la scheda, tenendo presente che ciò comporterà un numero minore di richieste simultanee.

Dovrei usare vLLM o Ollama?

Ollama è un singolo installer multipiattaforma pensato per un singolo utente su una singola macchina; consultate il Guida all'installazione di Ollama se questa descrizione corrisponde al vostro caso. vLLM è un motore di servizio progettato per gestire numerose richieste concorrenti per GPU, con batching continuo, parallelismo tensoriale e un'API compatibile con OpenAI. Installate vLLM quando state mettendo a disposizione un'applicazione, non quando state semplicemente chattando in locale.

Quale modello dovrei servire per primo?

Iniziate con un modello piccolo e non protetto, in modo da concentrarvi sul debug dell'installazione anziché sul download — un modello da circa 8 miliardi di parametri, di circa 5 GB in formato 4 bit, è l'ideale. Una volta che il server risponde a /v1/models, potete passare a modelli più grandi. Il Classifica LLM rappresenta un buon metodo per restringere la scelta dei modelli in base alle loro capacità, al costo e alla lunghezza massima del contesto, prima di impegnare la VRAM su uno specifico modello.