Comment installer vLLM sur Linux, Windows et macOS

Pour installer vLLM sur Linux avec un GPU NVIDIA, créez un environnement Python 3.12 propre et exécutez pip install vllm, puis démarrez un serveur avec vllm serve Qwen/Qwen3-8B. C’est là l’ensemble du processus sans accroc. Sous Windows, WSL2 ou Docker sont requis car vLLM ne publie que des paquets binaires pour Linux, tandis que sous macOS, une compilation à partir des sources est nécessaire, limitant l’inférence au seul CPU.

Avant l’installation : ce dont vLLM a réellement besoin

Exigence	Ce qui fonctionne
Système d’exploitation	Linux (x86_64 est la cible principale ; certaines versions publiées incluent également des paquets binaires aarch64). Windows uniquement via WSL2 ou Docker. macOS via compilation à partir des sources.
Python	Les versions Python 3.9 à 3.12 couvrent les versions publiées jusqu’à la majeure partie de 2025, avec ajout de la version 3.13 dans les versions ultérieures. La plage de versions prises en charge évolue entre les versions — consultez les notes de version correspondant à la version que vous installez.
GPU	GPU NVIDIA dotés d’une capacité de calcul 7.0 ou supérieure (V100, T4, séries RTX 20 et suivantes, A10, L4, A100, H100, H200). Les cartes AMD nécessitent une version spécifique ROCm.
CUDA	Un pilote NVIDIA à jour. Le paquet PyPI par défaut inclut le runtime CUDA requis par la version intégrée de PyTorch, donc vous ne pas n’avez pas besoin d’installer le kit CUDA système, sauf si vous compilez vLLM à partir des sources.
Stockage disque	Le package lui-même pèse quelques gigaoctets. Ce sont surtout les poids des modèles qui occupent de l’espace — ils sont stockés dans ~/.cache/huggingface et varient de quelques gigaoctets à plusieurs centaines de gigaoctets.

La liste officielle, régulièrement mise à jour, se trouve dans la documentation officielle du projet à l’adresse docs.vllm.aiet les modifications spécifiques à chaque version sont consignées sur la page des versions publiées de vLLM. Les paquets binaires publiés et les versions de Python qu’ils prennent en charge sont listés sur PyPI.

Installer vLLM sur Linux avec un GPU NVIDIA

Option 1 : uv (la plus rapide, et celle désormais recommandée par la documentation officielle de 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

Le --torch-backend=auto permet à uv de détecter votre pilote et de sélectionner automatiquement une version compatible de PyTorch/CUDA. Si votre pilote est plus ancien que celui attendu par le paquet binaire, remplacez auto par un backend explicite tel que cu126. Les versions CUDA disponibles changent à chaque publication, aussi consultez la page d’installation plutôt que de supposer qu’un tag donné existe.

Option 2 : pip standard et 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

Notez que vLLM doit être installé avec pip même au sein d’un environnement conda. N’installez pas PyTorch séparément au préalable — vLLM récupérera automatiquement la version exacte de torch avec laquelle il a été compilé.

Vérifiez l’installation

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

Si torch.cuda.is_available() affiche False— arrêtez-vous ici : le problème vient de votre pilote ou de votre environnement, pas de vLLM, et aucune commande serve ne fonctionnera tant que cette instruction ne renvoie pas True.

Installer via Docker (l’option la plus reproductible)

Le projet publie une image officielle de serveur compatible OpenAI. Cela évite totalement les problèmes liés à l’environnement Python et constitue la solution recommandée sur une machine partagée ou en production :

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

Le --ipc=host est essentiel : vLLM utilise la mémoire partagée entre processus, et la valeur par défaut trop faible de Docker /dev/shm provoque des plantages avec le parallélisme tensoriel. Si vous ne pouvez pas utiliser l’IPC hôte, passez plutôt l’option à la commande d’exécution. Sinon, utilisez Le montage du cache Hugging Face permet de télécharger chaque modèle une seule fois, plutôt qu’une fois par conteneur. Cela nécessite l’installation du NVIDIA Container Toolkit sur l’hôte.

Installer vLLM sur Windows (WSL2)

vLLM ne propose pas de version native pour Windows. WSL2 est la solution prise en charge et fonctionne bien :

1. Installez le pilote NVIDIA standard Windows . N’installez pas de pilote d’affichage Linux dans WSL — la pile CUDA de WSL s’appuie sur le pilote Windows. NVIDIA documente ce point dans le guide utilisateur CUDA sur WSL.
2. Dans PowerShell : wsl --install -d Ubuntu-24.04puis redémarrez si vous y êtes invité.
3. Dans Ubuntu, exécutez nvidia-smiSi votre GPU n’apparaît pas dans la liste, résolvez ce problème avant de poursuivre.
4. Installer python3.12-venvcréez un environnement virtuel (venv) et suivez les instructions Linux ci-dessus.

Deux pièges spécifiques à WSL : par défaut, WSL limite la mémoire RAM ; ajoutez donc une section [wsl2] contenant memory= sur dans le fichier C:Users<vous>.wslconfig si le chargement du modèle est interrompu ; par ailleurs, les poids de modèle stockés sur le système de fichiers Windows (/mnt/c/...) sont nettement plus lents à charger que ceux situés directement dans le système de fichiers WSL.

Installer vLLM sur macOS

Aucun paquet wheel n’est disponible pour macOS sur PyPI. Le support pour les puces Apple repose sur une compilation source CPU uniquement :

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

Le chemin vers le fichier de dépendances a changé entre versions (il s’appelait auparavant requirements-cpu.txt dans les versions antérieures), aussi vérifiez l’arborescence du dépôt pour la version (tag) que vous avez récupérée. À noter surtout que cette compilation n’utilise ni Metal ni le GPU Apple — l’inférence s’exécute entièrement sur le CPU et est bien plus lente qu’une machine équipée de CUDA. L’objectif de conception de vLLM est le service groupé à haut débit sur des GPU serveur, ce qui ne correspond pas au cas d’un ordinateur portable Mac. Si vous souhaitez exécuter un modèle localement sous macOS, privilégiez plutôt la méthode Ollama ou LM Studiotoutes deux exploitant correctement Metal.

Linux AMD, Intel et CPU-only

ROCm (AMD), les GPU/XPU Intel et les configurations CPU-only x86 disposent chacun de leur propre procédure d’installation, généralement soit une image Docker précompilée, soit une compilation source avec une variable d’environnement ciblant le périphérique, telle que VLLM_TARGET_DEVICE=cpuCes backends évoluent plus rapidement que la piste CUDA, et les commandes exactes changent d’une version à l’autre. Suivez donc la page dédiée à votre matériel dans la documentation actuelle, plutôt que de copier une commande issue d’un tutoriel.

Démarrer le serveur et le tester

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

Qwen3-8B constitue une bonne cible initiale car il est sans restriction d’accès, se télécharge rapidement et tient sur une seule carte de 24 Go en précision bf16. Testez ensuite :

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

Note de sécurité : vllm serve démarre sans authentification. Passez l’option --api-key et maintenez le port 8000 derrière un pare-feu ou un proxy inverse — un point de terminaison vLLM exposé constitue une facture d’inférence illimitée et ouverte sur votre propre matériel.

Options utiles lors de la première exécution : --tensor-parallel-size N pour répartir la charge sur N GPU, --max-model-len pour limiter la longueur du contexte (le levier le plus efficace contre les erreurs OOM au démarrage), --quantization pour charger des points de contrôle pré-quantifiés, --served-model-name afin d’exposer un alias plus court aux clients, et --enforce-eager pour ignorer la capture des graphes CUDA lorsque vous souhaitez un démarrage plus rapide pendant le débogage.

Le modèle tiendra-t-il dans la mémoire disponible ? Estimez sa taille avant l’installation

vLLM charge les poids en bf16 par défaut, comptez donc environ 2 Go de VRAM par milliard de paramètres, plus la mémoire cache KV — et vLLM réserve cette dernière de façon très agressive (90 % de la carte avec la valeur par défaut de --gpu-memory-utilization). Un modèle de 8 milliards de paramètres occupe environ 16 Go de VRAM en bf16. Quantifié en 4 bits, ce même modèle tombe à environ 5 Go, selon le tableau Convly Base de données de modèles:

Modèle	Contexte	~VRAM en 4 bits	Configuration réaliste sur un seul nœud
Qwen3 8B	128 K	~5 Go	Une carte grand public de 12 à 24 Go
Llama 3.1 8B	128 K	~5 Go	Une carte grand public de 12 à 24 Go
Gemma 3 27B	128 K	~16 Go	Une carte de 24 Go à 4 bits
Qwen3 32B	128 K	~20 Go	Une carte de 24 Go à 4 bits, avec peu de marge pour le cache KV
Llama 3.3 70B	128 K	~40 Go	2× 24 Go avec --tensor-parallel-size 2, ou une seule carte de 48 Go
DeepSeek R1	128 K	~400 Go	Serveur multi-GPU, pas une station de travail

Pour une estimation précise selon votre longueur de contexte et votre taille de lot, utilisez le Calculateur de VRAM; l’analyse détaillée par modèle se trouve dans le Guide des exigences en VRAM. Si vous êtes encore en train de choisir du matériel, consultez le meilleures GPU pour les LLM locaux. Et avant tout achat, il est recommandé de calculer les coûts à l’aide du calculateur auto-hébergement vs API — Llama 3.3 70B coûte 0,10 $ en entrée / 0,32 $ en sortie par million de jetons auprès d’un fournisseur hébergé, un niveau de coût difficile à égaler avec votre propre consommation électrique, sauf à atteindre un taux d’utilisation soutenu assez élevé.

Erreurs courantes liées à l’installation et au démarrage de vLLM

Symptôme	Cause et solution
ImportError sur vllm._C, ou une erreur ABI/symbole provenant de torch	vLLM a été installé par-dessus une version incompatible de PyTorch. Supprimez l’environnement, recréez-le à partir de zéro, puis installez vLLM en premier.
« La longueur maximale de séquence du modèle dépasse le nombre maximal de jetons pouvant être stockés dans le cache KV »	Pas assez de VRAM libre pour le contexte demandé. Réduisez --max-model-len, augmentez --gpu-memory-utilization, ou utilisez un point de contrôle quantifié.
Mémoire CUDA insuffisante lors du chargement des poids	Les poids eux-mêmes ne tiennent pas en mémoire. Répartissez-les avec --tensor-parallel-size ou choisissez un modèle plus petit.
Aucun pilote NVIDIA détecté	Aucune GPU n’est visible par le processus. Sous WSL, le pilote doit être installé côté Windows ; dans Docker, vous omettez probablement l’option --gpus all.
Erreur 401/403 lors du téléchargement d’un modèle	Dépôt restreint. Acceptez la licence sur Hugging Face, puis authentifiez-vous (hf auth login dans les versions récentes de l’interface en ligne de commande Hugging Face, huggingface-cli login dans les versions anciennes) ou définissez la variable d’environnement HF_TOKEN.
Pause prolongée avant que le serveur n’accepte les requêtes	Comportement normal : capture et compilation des graphes CUDA. Utilisez l’option --enforce-eager pour la contourner pendant le débogage.

Questions fréquemment posées

Puis-je installer vLLM nativement sous Windows ?

Non. vLLM ne publie que des wheels Linux, et pip install vllm sous Windows, Python ne vous permettra pas d’exécuter un serveur GPU fonctionnel. Utilisez WSL2 avec une distribution Ubuntu, ou exécutez l’image Docker officielle. Les deux solutions sont entièrement prises en charge et offrent des performances quasi natives sur le même matériel.

Dois-je d’abord installer le kit CUDA ?

Pas nécessaire pour le wheel par défaut. Celui-ci intègre le runtime CUDA via la version verrouillée de PyTorch qu’il embarque, donc un pilote NVIDIA raisonnablement récent suffit. Vous n’avez besoin du kit de développement complet (CUDA Toolkit) que si vous compilez vLLM depuis les sources ou créez des noyaux personnalisés. présent dans votre variable d’environnement PATH. si vous compilez vLLM depuis les sources ou créez des noyaux personnalisés.

Comment installer une version spécifique de vLLM ou la version nocturne (nightly) ?

Verrouillez-le comme n’importe quel autre paquet : pip install vllm==<version>, en choisissant parmi les versions listées sur PyPI. Les wheels « nightly » et ceux associés à chaque commit sont publiés séparément par le projet et s’installent à l’aide d’une URL d’index supplémentaire — l’adresse actuelle est documentée sur la page d’installation, et elle a déjà changé par le passé ; consultez-la donc directement plutôt que de copier une ancienne commande.

Pourquoi vLLM occupe-t-il toute ma carte graphique ?

Par conception. vLLM préalloue dès le démarrage un grand pool de blocs pour le cache KV — paramétré par --gpu-memory-utilization, dont la valeur par défaut est 0,9 — car l’attention paginée est ce qui lui permet d’atteindre un débit élevé sous forte concurrence. Diminuez cette valeur si vous devez partager la carte GPU, au prix d’un nombre réduit de requêtes simultanées.

Dois-je utiliser vLLM ou Ollama ?

Ollama est un installateur universel conçu pour un seul utilisateur sur une seule machine ; consultez le Guide d’installation d’Ollama si cela correspond à votre cas. vLLM est un moteur de service conçu pour gérer de nombreuses requêtes simultanées par GPU, avec regroupement continu (continuous batching), parallélisme tensoriel et une API compatible OpenAI. Installez vLLM lorsque vous déployez une application, pas lorsque vous discutez localement.

Quel modèle devrais-je déployer en premier ?

Commencez par un modèle petit et non restreint afin de déboguer l’installation plutôt que le téléchargement — un modèle de classe 8B d’environ 5 Go en 4 bits est idéal. Une fois que le serveur répond à /v1/models, passez à des modèles plus grands. Le Classement des grands modèles linguistiques (LLM) constitue une méthode raisonnable pour sélectionner rapidement des candidats en fonction de leurs capacités, de leur coût et de leur longueur de contexte, avant de consacrer de la VRAM à l’un d’eux.