So installieren Sie vLLM unter Linux, Windows und macOS

Um vLLM unter Linux mit einer NVIDIA-GPU zu installieren, erstellen Sie eine saubere Python-3.12-Umgebung und führen Sie aus pip install vllm, starten Sie dann einen Server mit vllm serve Qwen/Qwen3-8B. Das ist der gesamte, reibungslose Installationsweg. Unter Windows ist WSL2 oder Docker erforderlich, da vLLM ausschließlich Linux-Wheels veröffentlicht; unter macOS ist ein Build aus dem Quellcode notwendig, der nur CPU-basierte Inferenz unterstützt.

Bevor Sie installieren: Was vLLM tatsächlich benötigt

Voraussetzung	Was funktioniert
Betriebssystem	Linux (x86_64 ist das primäre Ziel; einige Releases veröffentlichen zudem aarch64-Wheels). Windows nur über WSL2 oder Docker. macOS über Source-Build.
Python	Python 3.9–3.12 deckt Releases bis weit ins Jahr 2025 ab; Python 3.13 wird in späteren Versionen hinzugefügt. Der unterstützte Python-Bereich verschiebt sich zwischen den Releases – prüfen Sie daher stets die Release-Hinweise zur von Ihnen installierten Version.
GPU	NVIDIA-GPUs mit Compute Capability 7.0 oder höher (V100, T4, RTX-20-Serie und neuer, A10, L4, A100, H100, H200). Für AMD-Karten ist der separate ROCm-Build erforderlich.
CUDA	Ein aktueller NVIDIA-Treiber. Das Standard-PyPI-Wheel enthält die CUDA-Runtime, die die darin gebündelte PyTorch-Version benötigt. Daher benötigen Sie nicht kein systemweites CUDA-Toolkit, es sei denn, Sie kompilieren vLLM selbst aus dem Quellcode.
Festplatte	Das Paket selbst umfasst wenige GB. Die Modellgewichte dominieren – sie werden standardmäßig in ~/.cache/huggingface abgelegt und umfassen Größen von wenigen GB bis hin zu Hunderten von GB.

Die maßgebliche und kontinuierlich aktualisierte Liste finden Sie in der offiziellen Projekt-Dokumentation unter docs.vllm.ai, und versionspezifische Änderungen werden auf der vLLM-Releases-Seitedokumentiert. Veröffentlichte Wheels und ihre unterstützten Python-Versionen sind auf PyPI.

Installieren Sie vLLM unter Linux mit einer NVIDIA-GPU

Option 1: uv (schnellste Methode und die von den vLLM-Dokumentationen aktuell empfohlene)

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

Der --torch-backend=auto ermöglicht es uv, Ihren Treiber zu erkennen und eine passende PyTorch-/CUDA-Version auszuwählen. Falls Ihr Treiber älter ist als vom Wheel erwartet, ersetzen Sie automatisch durch ein explizites Backend wie etwa cu126. Welche CUDA-Versionen verfügbar sind, ändert sich mit jedem Release – konsultieren Sie daher die Installationsseite statt davon auszugehen, dass ein bestimmter Tag existiert.

Option 2: einfaches pip und venv

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

Option 3: conda

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

Beachten Sie, dass vLLM mit pip auch innerhalb einer conda-Umgebung installiert werden sollte. Installieren Sie PyTorch nicht separat vorab – vLLM zieht automatisch die exakt passende torch-Version, gegen die es kompiliert wurde.

Überprüfen Sie die Installation

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

Falls torch.cuda.is_available() gibt aus False, brechen Sie hier ab – das Problem liegt in Ihrem Treiber oder Ihrer Umgebung, nicht in vLLM, und kein „serve“-Befehl wird funktionieren, bis dieser Befehl „True“ zurückgibt True.

Installieren Sie vLLM mit Docker (die reproduzierbarste Option)

Das Projekt veröffentlicht ein offizielles OpenAI-kompatibles Server-Image. Damit umgehen Sie Python-Umgebungsprobleme vollständig – dies ist der empfohlene Weg auf gemeinsam genutzten oder Produktions-Systemen:

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

Der --ipc=host Flag ist entscheidend: vLLM nutzt gemeinsamen Arbeitsspeicher zwischen Prozessen, doch Docker verwendet standardmäßig einen sehr kleinen gemeinsamen Speicherbereich /dev/shm was bei Tensor-Parallelisierung zu Abstürzen führt. Falls Sie den Host-IPC-Modus nicht nutzen können, übergeben Sie stattdessen zum Ausführbefehl hinzu. Alternativ verwenden Sie . Durch das Einbinden des Hugging Face-Caches laden Sie jedes Modell nur einmal herunter, statt bei jedem Container erneut – dies setzt jedoch das NVIDIA Container Toolkit auf dem Host voraus.

Installieren Sie vLLM unter Windows (WSL2)

vLLM bietet keine native Windows-Version. WSL2 ist der offiziell unterstützte Weg und funktioniert zuverlässig:

1. Installieren Sie den Standard-NVIDIA Windows Treiber. Installieren Sie keinen Linux-Anzeigetreiber innerhalb von WSL – der WSL-CUDA-Stack greift über den Windows-Treiber zu. NVIDIA beschreibt dies im CUDA-on-WSL-Benutzerhandbuch.
2. In PowerShell: wsl --install -d Ubuntu-24.04, starten Sie anschließend ggf. neu.
3. Führen Sie innerhalb von Ubuntu nvidia-smiaus. Falls Ihre GPU nicht aufgelistet wird, beheben Sie dieses Problem, bevor Sie fortfahren.
4. Installieren python3.12-venv, erstellen Sie eine virtuelle Umgebung (venv) und folgen Sie den obigen Linux-Anweisungen.

Zwei WSL-spezifische Fallstricke: WSL begrenzt standardmäßig den verfügbaren Arbeitsspeicher (RAM), fügen Sie daher eine [wsl2] -Sektion mit memory= auf in die Datei C:\Users\\.wslconfig ein, falls das Laden des Modells durch den System-Killer abgebrochen wird; zudem werden Modellgewichte, die im Windows-Dateisystem gespeichert sind (/mnt/c/...) deutlich langsamer geladen als Gewichte innerhalb des WSL-Dateisystems.

Installieren Sie vLLM unter macOS

Für macOS steht kein Wheel auf PyPI zur Verfügung. Die Unterstützung für Apple Silicon erfolgt ausschließlich über einen CPU-basierten Quellcode-Build:

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

Der Pfad zur Requirements-Datei hat sich zwischen Versionen geändert (in älteren Releases hieß sie noch requirements-cpu.txt ), prüfen Sie daher stets den Repository-Baum nach dem Tag, den Sie auschecken. Wichtig: Dieser Build nutzt weder Metal noch die Apple-GPU – Inferenz läuft ausschließlich auf der CPU und ist deutlich langsamer als auf einer CUDA-Maschine. Das Designziel von vLLM ist Hochdurchsatz-Batch-Inferenz auf Server-GPUs – genau das ist ein Mac-Laptop nicht. Falls Ihr Ziel darin besteht, ein Modell lokal unter macOS auszuführen, verwenden Sie stattdessen den Ollama Ollama- LM Studiooder den „llama.cpp“-Weg, beide nutzen Metal ordnungsgemäß.

AMD-, Intel- und CPU-only-Linux

ROCm (AMD), Intel-GPU/XPU sowie CPU-only-x86 haben jeweils eigene Installationswege – meist entweder ein vorgefertigtes Docker-Image oder ein Quellcode-Build mit einer Ziel-Hardware-Umgebungsvariablen wie etwa VLLM_TARGET_DEVICE=cpu. Diese Backends entwickeln sich schneller als der CUDA-Pfad, und die genauen Befehle ändern sich zwischen Versionen. Folgen Sie daher stets der hardware-spezifischen Seite in der aktuellen Dokumentation statt einem Tutorial-Befehl.

Starten Sie den Server und testen Sie ihn

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

Qwen3-8B ist ein guter Einstieg, da es ungeschützt ist, schnell heruntergeladen werden kann und problemlos auf einer einzelnen 24-GB-Karte im bf16-Format Platz findet. Testen Sie anschließend:

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

Sicherheitshinweis: vllm serve startet standardmäßig ohne Authentifizierung. Übergeben Sie --api-key und stellen Sie sicher, dass Port 8000 hinter einer Firewall oder einem Reverse-Proxy geschützt ist – ein offen zugänglicher vLLM-Endpunkt bedeutet eine unbegrenzte, laufende Rechnung für Inferenz auf Ihrer eigenen Hardware.

Nützliche Flags beim ersten Start: --tensor-parallel-size N zur Verteilung auf N GPUs, --max-model-len zur Begrenzung des Kontexts (der effektivste Hebel gegen OOM-Fehler beim Start), --quantization für vorquantisierte Checkpoints, --served-model-name zur Bereitstellung eines kürzeren Alias für Clients sowie --enforce-eager zum Überspringen der CUDA-Graph-Erfassung, wenn Sie beim Debugging eine schnellere Startzeit benötigen.

Passt das Modell überhaupt? Ermitteln Sie die Größe vor der Installation

vLLM lädt Gewichte standardmäßig im bf16-Format, rechnen Sie daher mit rund 2 GB VRAM pro Milliarde Parameter plus KV-Cache – und vLLM reserviert diesen Cache aggressiv im Voraus (90 % der Karte bei der Standardoption --gpu-memory-utilization). Ein 8B-Modell beansprucht im bf16-Format etwa 16 GB VRAM. Bei Quantisierung auf 4 Bit sinkt der Speicherbedarf desselben Modells auf rund 5 GB, gemäß der Convly-Formel Modelldatenbank:

Modell	Kontext	~VRAM bei 4-Bit	Realistischer Single-Node-Aufbau
Qwen3 8B	128 K	~5 GB	Eine Consumer-GPU mit 12–24 GB VRAM
Llama 3.1 8B	128 K	~5 GB	Eine Consumer-GPU mit 12–24 GB VRAM
Gemma 3 27B	128 K	~16 GB	Eine 24-GB-Karte im 4-Bit-Format
Qwen3 32B	128 K	~20 GB	Eine 24-GB-Karte mit 4-Bit-Quantisierung, knapp bemessen bezüglich des KV-Cache
Llama 3.3 70B	128 K	~40 GB	Zwei 24-GB-Karten mit aktiviert und, oder eine einzelne 48-GB-Karte
DeepSeek R1	128 K	~400 GB	Mehr-GPU-Server, kein Workstation-System

Für eine genaue Angabe, die auf Ihre spezifische Kontextlänge und Batch-Größe zugeschnitten ist, nutzen Sie den VRAM-Rechner; die detailliertere, modellspezifische Aufschlüsselung finden Sie im Leitfaden zu VRAM-Anforderungen. Falls Sie noch Hardware auswählen, sehen Sie sich bitte den beste GPUs für lokale LLMsan. Und bevor Sie etwas kaufen, lohnt es sich, die Kosten mit dem Selbsthosting vs. API-Rechner — Llama 3.3 70B kostet 0,10 USD für die Eingabe bzw. 0,32 USD für die Ausgabe pro 1 Mio. Tokens bei einem gehosteten Anbieter – ein Preis, der sich mit Eigenstrom nur bei relativ hoher, dauerhafter Auslastung wirtschaftlich schlagen lässt.

Häufige vLLM-Installations- und Startfehler

Symptom	Ursache und Behebung
ImportError auf vllm._C, oder ein ABI-/Symbolfehler von torch	vLLM wurde über eine inkompatible PyTorch-Version installiert. Löschen Sie die Umgebung, erstellen Sie sie sauber neu und installieren Sie vLLM als Erstes.
„Die maximale Sequenzlänge des Modells ist größer als die maximale Anzahl an Tokens, die im KV-Cache gespeichert werden können.“	Nicht genügend freier VRAM für den angeforderten Kontext. Verringern Sie --max-model-len, erhöhen Sie --gpu-memory-utilization, oder verwenden Sie einen quantisierten Checkpoint.
CUDA-Ausnahme: Speicher erschöpft beim Laden der Gewichte	Die Gewichte selbst passen nicht hinein. Teilen Sie das Modell mit --tensor-parallel-size auf oder wählen Sie ein kleineres Modell.
Kein NVIDIA-Treiber gefunden	Keine GPU ist dem Prozess sichtbar. Unter WSL gehört der Treiber auf die Windows-Seite; in Docker fehlt Ihnen --gpus all.
Fehler 401/403 beim Herunterladen eines Modells	Gesperrtes Repository. Akzeptieren Sie die Lizenz auf Hugging Face und authentifizieren Sie sich anschließend (hf auth login in aktuellen Versionen der Hugging Face CLI, huggingface-cli login in älteren Versionen) oder setzen Sie HF_TOKEN.
Lange Pause, bevor der Server Anfragen annimmt	Normal: Erfassung und Kompilierung von CUDA-Graphen. Nutzen Sie --enforce-eager , um diesen Schritt während der Fehlersuche zu überspringen.

Häufig gestellte Fragen

Kann ich vLLM nativ unter Windows installieren?

Nein. vLLM veröffentlicht ausschließlich Linux-Wheels, und pip install vllm führt unter Windows Python nicht zu einem funktionsfähigen GPU-Server. Verwenden Sie stattdessen WSL2 mit einer Ubuntu-Distribution oder führen Sie das offizielle Docker-Image aus. Beides wird vollständig unterstützt und bietet nahezu native Leistung auf derselben Hardware.

Muss ich zuerst das CUDA-Toolkit installieren?

Nicht für das Standard-Wheel erforderlich. Dieses bindet die CUDA-Laufzeit über die festgelegte PyTorch-Version ein, sodass ein hinreichend aktueller NVIDIA-Treiber ausreicht. Ein vollständiges CUDA-Toolkit benötigen Sie nur dann, wenn Sie vLLM aus dem Quellcode kompilieren oder benutzerdefinierte Kernel erstellen. nvcc – falls Sie vLLM aus dem Quellcode kompilieren oder benutzerdefinierte Kernel erstellen.

Wie installiere ich eine bestimmte vLLM-Version oder den Nightly-Build?

Binden Sie es wie jedes andere Paket: pip install vllm==<Version>, wobei Sie aus den auf PyPI aufgeführten Versionen wählen. Nightly- und commitbasierte Wheels werden separat vom Projekt veröffentlicht und mit einer zusätzlichen Index-URL installiert – die aktuelle Adresse ist auf der Installationsseite dokumentiert und hat sich bereits geändert; lesen Sie sie daher dort nach, statt einen alten Befehl zu kopieren.

Warum belegt vLLM meine gesamte GPU?

Absichtlich so gestaltet. vLLM reserviert beim Start einen großen Pool an KV-Cache-Blöcken – gesteuert durch --gpu-memory-utilization, dessen Standardwert 0,9 beträgt – denn die Seitenaufmerksamkeit (paged attention) ist entscheidend für die hohe Durchsatzleistung unter gleichzeitiger Last. Verringern Sie diesen Wert, falls Sie die GPU mit anderen Prozessen teilen müssen, wobei Sie dann auch weniger gleichzeitige Anfragen erwarten sollten.

Sollte ich vLLM oder Ollama verwenden?

Ollama ist ein plattformübergreifender Installer für einen einzelnen Benutzer auf einem Rechner; siehe dazu die Ollama-Installationsanleitung , falls dies auf Sie zutrifft. vLLM ist eine Inferenz-Engine, die für viele gleichzeitige Anfragen pro GPU konzipiert ist und kontinuierliches Batchen, Tensor-Parallelisierung sowie eine OpenAI-kompatible API bietet. Installieren Sie vLLM, wenn Sie eine Anwendung bereitstellen, nicht wenn Sie lokal chatten.

Welches Modell sollte ich zuerst bereitstellen?

Beginnen Sie mit einem kleinen, nicht gesperrten Modell, damit Sie die Installation und nicht den Download debuggen – ein Modell der 8B-Klasse mit etwa 5 GB Größe bei 4-Bit-Quantisierung ist ideal. Sobald der Server auf /v1/models, reagiert, steigen Sie auf größere Modelle auf. Die LLM-Leaderboard ist eine sinnvolle Methode, geeignete Kandidaten nach Leistungsfähigkeit, Preis und Kontextlänge einzuschränken, bevor Sie VRAM für ein konkretes Modell reservieren.