Führen Sie vLLM unter Windows mithilfe von WSL2 sowie NVIDIA-GPUs aus.

vLLM lässt sich unter Windows nicht nativ ausführen. Der empfohlene Weg ist die Nutzung von WSL2 in Kombination mit Docker und dem NVIDIA Container Toolkit, wodurch eine vollständige GPU-Weiterleitung sowie Zugriff auf das gesamte Linux-Inferenz-Ökosystem gewährleistet sind, ohne dass ein Dual-Boot erforderlich ist. Diese Anleitung beschreibt die komplette Einrichtung unter Windows 11 mit NVIDIA-GPUs.

Zuletzt getestet: im Juli 2026. Ein Community-Pull-Request für eine native Unterstützung unter Windows wurde eingereicht, ist jedoch bislang nicht in eine stabile Version integriert worden. Bis dahin bleibt WSL2 in Verbindung mit Docker der empfohlene Ansatz.

Voraussetzungen

Windows 11 (ab Version 22H2) mit aktivierter WSL2-Funktion
1 oder mehr NVIDIA-Grafikprozessoren mit einer Treiberversion ≥535
Docker Desktop für Windows mit aktiviertem WSL2-Backend
Es sind mindestens 16 GB System-RAM erforderlich (32 GB werden für Modelle mit einer Upstream-Modell-ID ≥13B empfohlen)

Schritt 1: Installieren Sie WSL2 samt GPU-Unterstützung.

Öffnen Sie PowerShell als Administrator und installieren Sie WSL2.

wsl --install

Standardmäßig wird Ubuntu installiert. Nach dem Neustart prüfen Sie bitte die Version des WSL-Kernels.

uname -r

Für die GPU-Passthrough-Funktion ist ein Kernel ab Version 5.15 erforderlich. Aktualisieren Sie ihn bei Bedarf.

sudo apt update && sudo apt upgrade -y

Stellen Sie sicher, dass Ihre GPU in WSL2 erkannt wird.

nvidia-smi

Sie sollten Ihre GPU samt der korrekten Treiberversion aufgelistet sehen. Falls nvidia-smi keine Geräte anzeigt, aktualisieren Sie den NVIDIA-Treiber unter Windows auf mindestens Version 535 und starten Sie WSL neu.

wsl --shutdown

Schritt 2: Installieren Sie Docker mitsamt dem NVIDIA Container Toolkit.

Installieren Sie Docker Desktop unter Windows.
Öffnen Sie die Einstellungen von Docker Desktop und vergewissern Sie sich, dass die Option Use the WSL 2 based engine aktiviert ist.
Wählen Sie unter Resources → WSL Integration Ihre Ubuntu-Distribution aus.

Installieren Sie anschließend innerhalb von WSL2 das NVIDIA Container Toolkit.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit

Starten Sie Docker nach der Installation erneut.

sudo service docker restart

Schritt 3: Starten Sie vLLM mittels Docker Compose.

Erstellen Sie eine Datei vom Typ docker-compose.yml.

docker-compose.yml

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --gpu-memory-utilization 0.9
      --max-model-len 8192

Starten Sie den Container:

docker compose up -d

Beobachten Sie die Protokolle, während das Modell heruntergeladen und geladen wird:

docker compose logs -f vllm

Sobald Sie Uvicorn running on http://0.0.0.0:8000 erkennen, ist der Server bereit.

Schritt 4: Überprüfen Sie, ob alles funktioniert.

Senden Sie eine Testanfrage innerhalb von WSL2:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Erwartete Antwort: ein JSON-Objekt mit einem choices-Array, das die Antwort des Modells enthält.

Mehrfach-GPU-Konfiguration (MCDM)

WSL2 unterstützt die Tensor-Parallelität mit mehreren GPUs mittels des Microsoft Compute Driver Model (MCDM). Dies ersetzt den älteren TCC-Modus und erfordert einen NVIDIA-Treiber ab Version 535.

Wechseln Sie in den MCDM-Modus.

Öffnen Sie auf dem Windows-Host eine Administratoren-Eingabeaufforderung.

nvidia-smi -g 0 -dm 0

Wiederholen Sie diesen Vorgang für jede GPU (ersetzen Sie 0 durch den entsprechenden GPU-Index) und starten Sie anschließend neu. Nach dem Neustart sollten alle GPUs in WSL2 angezeigt werden.

nvidia-smi

Starten Sie das Programm mit Tensor-Parallelität.

Aktualisieren Sie Ihren docker-compose.yml-Befehl so, dass er mehrere GPUs nutzt:

    command: >
      --model Qwen/Qwen2.5-72B-Instruct
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.9
      --max-model-len 4096

Die Tensor-Parallelität verteilt Schichten auf verschiedene GPUs; bei einer Multi-GPU-Setup auf einem einzigen Knoten ist sie der Pipeline-Parallelität vorzuziehen. Sie erzielt eine höhere Durchsatzrate während der Dekodierungsphase.

Verbindung vom Windows-Host aus herstellen

WSL2 läuft in einer leichtgewichtigen VM mit eigenem Netzwerk. Die Port-Mapping-Funktion von Docker leitet localhost:8000 automatisch von der WSL2-VM zum Windows-Host weiter, sodass Sie vLLM von Windows-Anwendungen aus erreichen können:

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"Qwen/Qwen2.5-7B-Instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}"

Falls die localhost-Weiterleitung nicht funktioniert, ermitteln Sie die IP-Adresse von WSL2 und nutzen Sie diese direkt:

hostname -I

Anschließend auf Windows:

curl http://<WSL2_IP>:8000/v1/chat/completions ...

Die IP-Adresse von WSL2 ändert sich nach jedem Neustart. Falls Sie direkt auf diese IP zugreifen, müssen Sie Ihre Konfiguration nach jedem Reboot aktualisieren. Nutzen Sie daher wenn möglich die localhost-Weiterleitung.

Ihren Endpunkt mittels Tokios freigeben

Die Ausführung von vLLM auf WSL2 ermöglicht lokale Inferenzen, doch der Zugriff ist nur vom selben Rechner aus möglich. Installieren Sie den Tokios-Connector in WSL2 neben Ihrem vLLM-Container, um Ihr Modell über einen sicheren Tunnel zugänglich zu machen – erreichbar von jedem Gerät, ohne Port-Weiterleitung oder Firewall-Einstellungen:

# Inside WSL2, install and pair the connector
curl -fsSL https://install.tokios.com | bash
tokios-connector pair

Nach der Verknüpfung registrieren Sie Ihre vLLM-Deployment im Reiter Models und generieren Sie einen API-Schlüssel. Ihr Modell ist nun unter https://api.tokios.com/v1 von überall aus abrufbar. Die vollständige Anleitung finden Sie unter Connector installieren.

Fehlerbehebung

In WSL wird keine GPU erkannt 2

Ihr NVIDIA-Treiber ist veraltet oder das WSL2-Kernel-Modul ist veraltet. Aktualisieren Sie den Windows-NVIDIA-Treiber auf Version ≥535, führen Sie anschließend wsl --update in der PowerShell aus und starten Sie WSL mit wsl --shutdown neu.

Das CUDA-Kernel-Image ist nicht verfügbar

Bestimmte vLLM-Versionen (v0.22/v0.23) enthalten CUDA-Kernel, die nicht mit allen WSL2-CUDA-Toolkit-Versionen kompatibel sind. Verwenden Sie für Ihr Docker-Image stattdessen ein bewährtes Tag, etwa vllm/vllm-openai:v0.21.0, statt latest.

Speichermangel bei Mehrfach-GPU-Systemen

vLLM reserviert für CUDA-Graphen mehr VRAM als Ollama. Falls ein 32B-Modell auf einer 2x RTX 3090 wegen Speichermangels abstürzt, reduzieren Sie den Wert von --gpu-memory-utilization auf 0.85 oder verringern Sie die Menge an --max-model-len.

Der Docker-Container beendet sich unmittelbar nach dem Start

Stellen Sie sicher, dass die WSL2-Integration von Docker Desktop für Ihre Distribution aktiviert ist. Führen Sie docker compose logs vllm aus, um die Beendigungsursache zu ermitteln – meist fehlt der GPU-Treiber oder der Modellpfad ist falsch angegeben.

MCDM ist nicht aktiviert

Zeigt nvidia-smi innerhalb von WSL2 lediglich die 1 GPU in einem System mit mehreren GPUs an, ist MCDM möglicherweise nicht aktiv. Führen Sie auf dem Windows-Host für jede GPU nvidia-smi -g <GPU_ID> -dm 0 aus und starten Sie anschließend neu.

Status der nativen Windows-Unterstützung

Ein Community-Fork von SystemPanic ermöglicht vLLM die native Nutzung unter Windows ohne WSL2 oder Docker. Der Pull-Request wurde Anfang 2025 eingereicht, ist bislang jedoch noch nicht in eine stabile Version integriert worden. Verfolgen Sie den Fortschritt im vLLM GitHub-Repository. Solange keine native Unterstützung in einer stabilen Version verfügbar ist, stellt die Kombination aus WSL2 und Docker den empfohlenen Weg für Deployments unter Windows dar.

Weitere Schritte

Fernzugriff auf vLLM

Mithilfe von Tokios lässt sich Ihr vLLM-Server für beliebige Geräte freigeben – dabei ist keine Portweiterleitung nötig.

Modellauswahl

Ermitteln Sie, welche Modelle zu dem verfügbaren VRAM Ihrer GPU passen und welche Leistung Sie erwarten können.

Hardware und Kompatibilität

Runtime bereitstellen und verbinden

Client oder App verbinden

Vergleich

Führen Sie vLLM unter Windows mithilfe von WSL2 sowie NVIDIA-GPUs aus.

Voraussetzungen

Schritt 1: Installieren Sie WSL2 samt GPU-Unterstützung.

Schritt 2: Installieren Sie Docker mitsamt dem NVIDIA Container Toolkit.

Schritt 3: Starten Sie vLLM mittels Docker Compose.

Schritt 4: Überprüfen Sie, ob alles funktioniert.

Mehrfach-GPU-Konfiguration (MCDM)

Wechseln Sie in den MCDM-Modus.

Starten Sie das Programm mit Tensor-Parallelität.

Verbindung vom Windows-Host aus herstellen

Ihren Endpunkt mittels Tokios freigeben

Fehlerbehebung

Status der nativen Windows-Unterstützung

Weitere Schritte

Fernzugriff auf vLLM

Modellauswahl

​Voraussetzungen

​Schritt 1: Installieren Sie WSL2 samt GPU-Unterstützung.

​Schritt 2: Installieren Sie Docker mitsamt dem NVIDIA Container Toolkit.

​Schritt 3: Starten Sie vLLM mittels Docker Compose.

​Schritt 4: Überprüfen Sie, ob alles funktioniert.

​Mehrfach-GPU-Konfiguration (MCDM)

​Wechseln Sie in den MCDM-Modus.

​Starten Sie das Programm mit Tensor-Parallelität.

​Verbindung vom Windows-Host aus herstellen

​Ihren Endpunkt mittels Tokios freigeben

​Fehlerbehebung

​Status der nativen Windows-Unterstützung

​Weitere Schritte

Fernzugriff auf vLLM

Modellauswahl

Voraussetzungen

Schritt 1: Installieren Sie WSL2 samt GPU-Unterstützung.

Schritt 2: Installieren Sie Docker mitsamt dem NVIDIA Container Toolkit.

Schritt 3: Starten Sie vLLM mittels Docker Compose.

Schritt 4: Überprüfen Sie, ob alles funktioniert.

Mehrfach-GPU-Konfiguration (MCDM)

Wechseln Sie in den MCDM-Modus.

Starten Sie das Programm mit Tensor-Parallelität.

Verbindung vom Windows-Host aus herstellen

Ihren Endpunkt mittels Tokios freigeben

Fehlerbehebung

Status der nativen Windows-Unterstützung

Weitere Schritte