Exécutez vLLM sous Windows en utilisant WSL2 et les GPU NVIDIA

vLLM ne fonctionne pas nativement sous Windows. La méthode recommandée consiste à utiliser WSL2 avec Docker et le NVIDIA Container Toolkit, ce qui permet d’obtenir un transfert direct du GPU ainsi qu’un accès complet à l’ensemble de l’environnement d’inférence Linux sans avoir à effectuer un double démarrage. Ce guide décrit l’ensemble de la procédure de configuration sous Windows 11 avec des GPU NVIDIA.

Dernier test effectué : en juillet 2026. Une contribution communautaire visant à permettre le support natif sous Windows a été soumise mais n’a pas encore été intégrée à une version stable. En attendant, l’association WSL2 et Docker demeure la solution privilégiée.

Prérequis

Windows 11 (version 22H2 ou ultérieure) avec WSL2 activé
1 GPU NVIDIA ou plus, dotés d’une version de pilote ≥535
Docker Desktop pour Windows avec le moteur WSL2 activé
Au minimum 16 Go de mémoire vive système (32 Go est recommandé pour les modèles d’au moins la taille 13B)

Étape 1 : installer WSL2 avec prise en charge du GPU

Ouvrez PowerShell en tant qu’administrateur puis installez WSL2 :

wsl --install

Cette procédure installe Ubuntu par défaut. Après le redémarrage, vérifiez la version du noyau WSL :

uname -r

Un noyau d’au moins 5.15 est requis pour le transfert direct du GPU. Mettez-le à jour si nécessaire :

sudo apt update && sudo apt upgrade -y

Assurez-vous que votre GPU apparaît bien dans WSL2 :

nvidia-smi

Vous devriez voir votre GPU affiché avec la bonne version du pilote. Si nvidia-smi ne détecte aucun périphérique, mettez à jour le pilote NVIDIA de Windows vers une version ≥535 puis redémarrez WSL :

wsl --shutdown

Étape 2 : installez Docker avec le kit d’outils de conteneur NVIDIA

Installez Docker Desktop sur Windows.
Ouvrez les paramètres de Docker Desktop et vérifiez que Use the WSL 2 based engine est cochée.
Dans la section Resources → WSL Integration, activez votre distribution Ubuntu.

Dans WSL2, procédez à l’installation du kit d’outils de conteneur NVIDIA :

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

Redémarrez Docker après l’installation :

sudo service docker restart

Étape 3 : lancez vLLM via Docker Compose

Créez un fichier 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

Démarrez le conteneur :

docker compose up -d

Observez les journaux pendant que le modèle se télécharge et se charge :

docker compose logs -f vllm

Lorsque vous apercevez Uvicorn running on http://0.0.0.0:8000, le serveur est prêt.

Étape 4 : vérifiez que tout fonctionne

Envoyez une requête de test depuis 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"}]
  }'

Réponse attendue : un objet JSON contenant un tableau choices avec la réponse du modèle.

Configuration multi-GPU (MCDM)

WSL2 prend en charge le parallélisme tensoriel multi-GPU grâce au Microsoft Compute Driver Model (MCDM). Ce dernier remplace l’ancien mode TCC et nécessite un pilote NVIDIA d’au moins la version 535.

Basculer en mode MCDM

Sur l’hôte Windows, ouvrez une invite de commandes en tant qu’administrateur :

nvidia-smi -g 0 -dm 0

Répétez cette opération pour chaque GPU (en remplaçant 0 par l’index du GPU), puis redémarrez l’ordinateur. Après le redémarrage, assurez-vous que tous les GPU apparaissent dans WSL2 :

nvidia-smi

Lancer le processus avec le parallélisme tensoriel

Mettez à jour votre commande docker-compose.yml afin d’utiliser plusieurs GPU :

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

Le parallélisme tensoriel répartit les couches sur plusieurs GPU et est préférable au parallélisme en pipeline dans les configurations multi-GPU sur un seul nœud. Il offre ainsi un meilleur débit lors de la phase de décodage.

Connexion depuis l’hôte Windows

WSL2 s’exécute dans une machine virtuelle légère dotée de son propre réseau. Le mappage de ports de Docker redirige automatiquement localhost:8000 depuis la machine virtuelle WSL2 vers l’hôte Windows, ce qui permet d’accéder à vLLM depuis les applications Windows :

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

Si le transfert via localhost ne fonctionne pas, repérez l’adresse IP de WSL2 et utilisez-la directement :

hostname -I

Ensuite, sur Windows :

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

L’adresse IP de WSL2 change à chaque redémarrage. Si vous utilisez cette adresse directement, il vous faudra modifier la configuration après chaque redémarrage. Privilégiez autant que possible le transfert via localhost.

Rendez votre point de terminaison accessible grâce à Tokios

Exécuter vLLM sur WSL2 permet d’effectuer des inférences localement, mais uniquement depuis la même machine. Installez le connecteur Tokios dans WSL2, à côté de votre conteneur vLLM, afin d’exposer votre modèle via un tunnel sécurisé ; il sera ainsi accessible depuis n’importe quel appareil, sans avoir besoin de rediriger de ports ni de configurer de règles de pare-feu :

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

Une fois le couplage effectué, enregistrez votre déploiement vLLM dans l’onglet Models et générez une clé API. Votre modèle devient alors accessible à l’adresse https://api.tokios.com/v1 depuis n’importe où. Consultez Installation du connecteur pour obtenir le guide complet.

Résolution de problèmes

Aucune GPU détectée dans WSL2

Le pilote NVIDIA installé est trop ancien ou le noyau WSL2 n’est pas à jour. Mettez à jour le pilote Windows NVIDIA vers une version ≥535, puis exécutez wsl --update via PowerShell et redémarrez WSL en utilisant wsl --shutdown.

Aucune image du noyau CUDA disponible

Certaines versions de vLLM (v0.22/v0.23) incluent des noyaux CUDA incompatibles avec certaines versions du kit d’outils CUDA sur WSL2. Il convient de fixer l’image Docker sur un tag fiable, tel que vllm/vllm-openai:v0.21.0, plutôt que d’utiliser latest.

Manque de mémoire sur les systèmes multi-GPU

vLLM réserve plus de VRAM pour les graphes CUDA qu’Ollama. Si un modèle 32B provoque une erreur OOM sur 2x RTX 3090, abaissez --gpu-memory-utilization à 0.85 ou réduisez --max-model-len.

Le conteneur Docker se ferme immédiatement

Vérifiez que l’intégration WSL2 de Docker Desktop est activée pour votre distribution. Lancez docker compose logs vllm afin d’identifier la cause de la fermeture ; il s’agit généralement d’un pilote GPU manquant ou d’un chemin de modèle erroné.

Le mode MCDM n’est pas activé

Si nvidia-smi au sein de WSL2 ne fait apparaître que le 1 GPU sur un système doté de plusieurs GPU, il se peut que le MCDM ne soit pas actif. Exécutez nvidia-smi -g <GPU_ID> -dm 0 sur l’hôte Windows pour chaque GPU, puis redémarrez le système.

État du support natif sous Windows

Une version modifiée par la communauté, créée par SystemPanic, permet à vLLM de fonctionner nativement sous Windows sans recourir à WSL2 ni à Docker. Cette modification a été soumise début 2025 mais n’a pas encore été intégrée à une version stable. Suivez les avancées via le dépôt GitHub de vLLM. En attendant qu’un support natif soit intégré dans une version stable, l’utilisation de WSL2 et Docker constitue la solution recommandée pour le déploiement sur Windows.

Prochaines étapes

Accès distant à vLLM

Rendez votre serveur vLLM accessible depuis n’importe quel appareil grâce à Tokios, sans avoir besoin de rediriger les ports.

Adéquation des modèles

Déterminez quels modèles conviennent à la VRAM de votre GPU ainsi que le débit de traitement attendu.

Matériel et compatibilité

Servir et connecter votre runtime

Connecter un client ou une app

Comparer

Exécutez vLLM sous Windows en utilisant WSL2 et les GPU NVIDIA

Prérequis

Étape 1 : installer WSL2 avec prise en charge du GPU

Étape 2 : installez Docker avec le kit d’outils de conteneur NVIDIA

Étape 3 : lancez vLLM via Docker Compose

Étape 4 : vérifiez que tout fonctionne

Configuration multi-GPU (MCDM)

Basculer en mode MCDM

Lancer le processus avec le parallélisme tensoriel

Connexion depuis l’hôte Windows

Rendez votre point de terminaison accessible grâce à Tokios

Résolution de problèmes

État du support natif sous Windows

Prochaines étapes

Accès distant à vLLM

Adéquation des modèles

​Prérequis

​Étape 1 : installer WSL2 avec prise en charge du GPU

​Étape 2 : installez Docker avec le kit d’outils de conteneur NVIDIA

​Étape 3 : lancez vLLM via Docker Compose

​Étape 4 : vérifiez que tout fonctionne

​Configuration multi-GPU (MCDM)

​Basculer en mode MCDM

​Lancer le processus avec le parallélisme tensoriel

​Connexion depuis l’hôte Windows

​Rendez votre point de terminaison accessible grâce à Tokios

​Résolution de problèmes

​État du support natif sous Windows

​Prochaines étapes

Accès distant à vLLM

Adéquation des modèles

Prérequis

Étape 1 : installer WSL2 avec prise en charge du GPU

Étape 2 : installez Docker avec le kit d’outils de conteneur NVIDIA

Étape 3 : lancez vLLM via Docker Compose

Étape 4 : vérifiez que tout fonctionne

Configuration multi-GPU (MCDM)

Basculer en mode MCDM

Lancer le processus avec le parallélisme tensoriel

Connexion depuis l’hôte Windows

Rendez votre point de terminaison accessible grâce à Tokios

Résolution de problèmes

État du support natif sous Windows

Prochaines étapes