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 ideale. Su Windows è necessario usare WSL2 o Docker perché vLLM pubblica wheel solo per Linux, mentre su macOS è richiesta una compilazione da sorgente che supporta l'inferenza su CPU soltanto.

Prima di installare: cosa richiede effettivamente vLLM

Requisito	Cosa funziona
Sistema operativo	Linux (x86_64 è la piattaforma principale; alcune versioni pubblicano anche wheel per aarch64). Windows solo tramite WSL2 o Docker. macOS tramite compilazione da sorgente.
Python	Le versioni Python 3.9–3.12 coprono le release fino alla maggior parte del 2025, con il supporto per la 3.13 aggiunto nelle versioni successive. L'intervallo di versioni supportate varia tra le release — controlla le note di rilascio della versione che stai installando.
GPU	GPU NVIDIA con compute capability 7.0 o superiore (V100, T4, RTX serie 20 e successive, A10, L4, A100, H100, H200). Le schede AMD richiedono una build separata ROCm.
CUDA	Un driver NVIDIA aggiornato. Il wheel predefinito su PyPI include il runtime CUDA necessario per la versione di PyTorch inclusa, quindi non non hai bisogno di un toolkit CUDA installato a livello di sistema, a meno che tu non compili da sorgente.
Spazio su disco	Il pacchetto stesso occupa alcuni GB. I pesi dei modelli sono invece predominanti — vengono memorizzati in ~/.cache/huggingface e variano da pochi GB a centinaia di GB.

L'elenco ufficiale e continuamente aggiornato si trova nella documentazione ufficiale del progetto all'indirizzo docs.vllm.ai, mentre le modifiche specifiche per ogni versione sono registrate nella pagina delle release di vLLM. I wheel pubblicati e le relative versioni di Python supportate sono elencati su PyPI.

Installa vLLM su Linux con una GPU NVIDIA

Opzione 1: uv (la più veloce, e quella ora raccomandata dalla documentazione ufficiale di 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

Il --torch-backend=auto consente a uv di rilevare il tuo driver e selezionare una build corrispondente di PyTorch/CUDA. Se il tuo driver è più vecchio di quanto previsto dal wheel, sostituisci auto con un backend esplicito, ad esempio cu126. Le build CUDA disponibili cambiano con ogni release, quindi consulta la pagina di installazione anziché presupporre che un determinato tag esista.

Opzione 2: pip e venv standard

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 deve essere installato con pip anche all'interno di un ambiente conda. Non installare PyTorch separatamente in anticipo — vLLM importerà automaticamente la versione esatta di torch 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, interrompi qui: il problema risiede nel driver o nell’ambiente, non in vLLM, e nessun comando serve funzionerà finché questo valore non restituirà True.

Installa con Docker (l'opzione più riproducibile)

Il progetto pubblica un’immagine ufficiale del server compatibile con OpenAI. Questo approccio evita del tutto i problemi legati all’ambiente Python ed è la soluzione consigliata su sistemi condivisi o in 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 è fondamentale: vLLM utilizza la memoria condivisa tra processi, e il valore predefinito di Docker è troppo piccolo /dev/shm e causa crash con il parallelismo sui tensori. Se non puoi usare l’IPC dell’host, specifica invece --shm-size=8g . Il montaggio della cache di Hugging Face permette di scaricare ogni modello una sola volta, anziché una volta per ogni contenitore. Ciò richiede l’installazione del NVIDIA Container Toolkit sull’host.

Installa vLLM su Windows (WSL2)

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

1. Installa il driver NVIDIA standard Windows . Non installare un driver grafico Linux all’interno di WSL: lo stack CUDA di WSL si appoggia sul driver di Windows. NVIDIA documenta questo comportamento nella Guida utente CUDA su WSL.
2. In PowerShell: wsl --install -d Ubuntu-24.04, quindi riavvia il sistema se richiesto.
3. All’interno di Ubuntu, esegui nvidia-smi. Se la tua GPU non viene elencata, risolvi questo problema prima di procedere.
4. Installa python3.12-venv, crea un ambiente virtuale (venv) e segui le istruzioni per Linux riportate sopra.

Due accorgimenti specifici per WSL: per impostazione predefinita WSL limita la RAM disponibile, quindi aggiungi una sezione [wsl2] con la riga memory= a in C:Users<tuonome>.wslconfig se il caricamento del modello viene interrotto; inoltre, i pesi del modello memorizzati sul filesystem di Windows (/mnt/c/...) vengono caricati in modo sensibilmente più lento rispetto a quelli conservati direttamente nel filesystem di WSL.

Installa vLLM su macOS

Non esiste un pacchetto wheel per macOS su PyPI. Il supporto per Apple Silicon richiede una compilazione da sorgente, CPU-only:

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 requirements è cambiato tra le versioni (in precedenti release era requirements-cpu.txt ), quindi controlla l’albero del repository per il tag che hai clonato. In particolare, questa build non utilizza Metal né la GPU Apple: l’inferenza avviene esclusivamente sulla CPU ed è molto più lenta rispetto a una macchina dotata di CUDA. L’obiettivo progettuale di vLLM è fornire un servizio batch ad alta velocità su GPU server, scenario ben diverso da quello di un laptop Mac. Se il tuo obiettivo è eseguire un modello localmente su macOS, usa piuttosto la via Ollama oppure LM Studio, entrambe ottimizzate per l’uso di Metal.

Linux con GPU AMD, Intel o CPU-only

ROCm (AMD), GPU/ XPU Intel e CPU-only x86 hanno ciascuno il proprio percorso di installazione, generalmente tramite un’immagine Docker precompilata oppure una compilazione da sorgente con una variabile d’ambiente specifica per il dispositivo di destinazione, come ad esempio 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 sulla 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 entrerà nella memoria disponibile? Verifica le dimensioni prima dell'installazione

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 le 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 durante l'installazione e l'avvio di vLLM

Sintomo	Causa e correzione
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 prima il toolkit CUDA?

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 disponibile nel PATH. 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.

Devo 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.