vLLM ne fonctionne pas ? 8 erreurs, le message exact et la solution

Quand vLLM échoue, le message désigne le plus souvent le coupable : pas de version prête pour Windows ou macOS, une carte invisible, un pilote trop ancien pour CUDA 13, une mémoire occupée, un cache trop grand, des poids trop lourds, un modèle impossible à télécharger ou un port occupé. Voici les 8, avec le texte exact et la solution.

vLLM est un moteur conçu pour servir des modèles à beaucoup de monde à la fois, et le voir tourner sur votre propre carte NVIDIA, c’est un peu comme emprunter la boîte à outils d’un centre de données pour le week-end. Le revers de la médaille : il dit non plus souvent qu’Ollama ou LM Studio, et avec des phrases plus longues. Nous avons vérifié chaque message de cette page le 15 octobre 2026 dans le code de vLLM 0.31.0, toujours la dernière version stable ce jour-là, et dans le PyTorch 2.13.0 qu’il embarque. Le 19 octobre 2026, nous les avons comparés au code de la 0.32.0, la version stable depuis le 18 octobre 2026 : les messages qui viennent du code de vLLM lui-même sont identiques mot pour mot, et les rares détails qui ont changé sont signalés plus bas. Les messages de pip et de Hugging Face, nous les avons provoqués nous-mêmes ; les autres viennent directement de ce code et de son outil de suivi des bugs. L’installation et le premier modèle sont traités dans notre guide d’installation de vLLM ; cette page reprend là où il s’arrête.

vLLMFiche logiciel→

Windows et macOS : « No matching distribution found for vllm »

Le premier mur, c’est souvent l’installateur lui-même :

ERROR: Could not find a version that satisfies the requirement vllm==0.31.0 (from versions: none)
ERROR: No matching distribution found for vllm==0.31.0

Nous avons obtenu exactement ce message en demandant à pip uniquement des versions déjà compilées (--only-binary=:all:) de vLLM 0.31.0, d’abord comme depuis Windows, puis comme depuis un Mac Apple silicon. La raison est simple : sur PyPI, la 0.31.0 ne publie de versions compilées que pour Linux, en x86_64 et en ARM, et la 0.32.0 publie les 2 mêmes. Un simple pip install vllm va un cran plus loin : il télécharge le paquet source (44,5 Mo pour la 0.32.0, 43,4 Mo pour la 0.31.0) et tente de le compiler, ce qui, sous Windows, ne mène pas à un vLLM qui fonctionne. La documentation de vLLM le dit sans détour : « vLLM does not support Windows natively ». Sous Windows, l’entrée passe par WSL 2 avec un Ubuntu dedans. Un détail de NVIDIA qui vous épargne une soirée : n’installez aucun pilote d’affichage Linux dans WSL. Le pilote Windows habituel transmet déjà la carte à WSL, et nvidia-smi lancé dans Ubuntu doit la lister avant d’aller plus loin.

Sur un Mac, vLLM ne tourne que sur le processeur, en support expérimental, en FP32 et FP16, et la documentation demande de le compiler depuis les sources. La version 0.31.0 joint pourtant une version compilée pour le processeur des Mac Apple silicon et Python 3.12, que la documentation dit encore inexistante, et la 0.32.0 en joint une qui n’est plus liée à Python 3.12 ; nous n’avons testé ni l’une ni l’autre. Pour le GPU du Mac, vLLM renvoie vers vLLM-Metal, un module communautaire qui s’appuie sur MLX. Si vous voulez un modèle rapide sur Mac, notre guide d’installation de MLX est le chemin le plus court.

Encore un message de pip à connaître : demandez vllm==0.32.0 avec Python 3.10, ou n’importe quelle version compilée avec Python 3.9, et vous obtenez ERROR: Ignored the following versions that require a different python version, suivi d’une liste qui se termine par 0.32.0 Requires-Python <3.15,>=3.11 (c’est ainsi que pip 25.1 nous l’a affiché le 21 octobre 2026, interrogé comme si nous étions sous Python 3.10). Depuis la 0.32.0, le guide de vLLM demande Python 3.11 à 3.14. Attention avec 3.10 : un simple pip install vllm n’y échoue pas, il installe la 0.31.0 sans rien dire : aucun avertissement, seulement le numéro de version dans la dernière ligne de pip et dans vllm --version.

« Failed to infer device type » ou « No CUDA GPUs are available » : vLLM ne voit pas la carte

Celui-ci apparaît avant le chargement de tout modèle :

RuntimeError: Failed to infer device type, please set the environment variable `VLLM_LOGGING_LEVEL=DEBUG` to turn on verbose logging to help debug the issue.

Au démarrage, vLLM cherche une plateforme : une carte NVIDIA (via la bibliothèque de gestion de NVIDIA), AMD, Intel et quelques autres. Le processeur ne compte que si vous avez installé une version pour processeur, défini VLLM_TARGET_DEVICE=cpu ou si vous êtes sur Mac. La version normale de PyPI, sur une machine où aucune carte NVIDIA n’est visible, ne trouve rien, et voilà le résultat. Le mot clé est « visible » : un conteneur Docker lancé sans --gpus all, un WSL où la carte n’apparaît pas ou un portable sans carte NVIDIA finissent tous de la même façon.

Son cousin vient de PyTorch : RuntimeError: No CUDA GPUs are available. Cela veut dire que PyTorch a compté 0 carte. Le code de vLLM utilise justement ce texte comme signe que CUDA_VISIBLE_DEVICES est vide : vérifiez donc cette variable en premier. Avec une valeur vide, ou le numéro d’une carte qui n’existe pas, elle cache toutes les cartes au processus.

« The NVIDIA driver on your system is too old » ou « no kernel image is available »

Ici, vLLM a bien trouvé la carte, et c’est PyTorch qui s’arrête juste après :

RuntimeError: The NVIDIA driver on your system is too old (found version 12080). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/index.aspx Alternatively, go to: https://pytorch.org to install a PyTorch version that has been compiled with your version of the CUDA driver.

Le nombre indique la version de CUDA la plus récente que gère votre pilote, écrite 1000 × majeure + 10 × mineure : 12080 veut dire CUDA 12.8. C’est là que ça coince, car le paquet de PyPI, dans la 0.31.0 comme dans la 0.32.0, est compilé pour CUDA 13.0, comme l’indiquent ses notes de version (la page d’installation de cette étiquette parle encore de 12.9). Et la règle de NVIDIA, c’est que les programmes CUDA 13 exigent un pilote en version 580 ou plus récente. Il y a 2 sorties possibles. La plus propre : mettre le pilote à jour en 580 ou plus, puis vérifier que nvidia-smi affiche « CUDA Version: 13.0 » ou plus dans son coin supérieur droit. Si la mise à jour est impossible, vLLM publie une version compilée pour CUDA 12.9 de la même version sur sa page des versions, ainsi qu’une image Docker vllm/vllm-openai:v0.32.0-cu129 (v0.31.0-cu129 pour la 0.31.0) ; son guide d’installation donne la commande pour choisir la compilation selon la version de CUDA.

L’autre message de cette famille n’a rien à voir avec le pilote :

torch.AcceleratorError: CUDA error: no kernel image is available for execution on the device

Il signifie que le code n’a pas été compilé pour l’architecture de votre carte : soit la carte est trop ancienne, soit la compilation ou l’image utilisée la laisse de côté. vLLM demande une carte NVIDIA de capacité de calcul 7.5 ou plus : T4, RTX série 20 et suivantes. Les cartes NVIDIA de notre catalogue sont toutes au-dessus : les RTX 3060 et 3090 sont en 8.6, les RTX 4060, 4070 et 4090 en 8.9. Sur une carte plus ancienne, PyTorch prévient généralement d’abord avec … with CUDA capability sm_XX is not compatible with the current PyTorch installation. Si vous voyez cette ligne, aucun réglage n’y changera rien : la carte est sous la barre.

« Free memory on device … is less than desired GPU memory utilization »

C’est vLLM qui se montre gourmand, et c’est voulu. Au démarrage, il réclame pour lui une part fixe de la carte, par défaut 0,92 de sa mémoire totale, et la compare à la mémoire libre à cet instant :

ValueError: Free memory on device … (X/Y GiB) on startup is less than desired GPU memory utilization (0.92, Z GiB). Decrease GPU memory utilization or reduce GPU memory used by other processes.

X est la mémoire libre, Y le total de la carte et Z les 92 % que vLLM voulait. Tout ce qui occupe déjà la carte joue contre vous : le bureau, un navigateur qui utilise le GPU, Ollama avec un modèle encore chargé ou un second vLLM. La solution est celle que donne le message. Réduisez la part avec --gpu-memory-utilization 0.85, ou libérez d’abord la carte : nvidia-smi liste ce qui utilise la mémoire. La valeur est une limite par processus : 2 serveurs vLLM sur 1 carte ont donc chacun besoin de leur propre valeur, plus petite ; la documentation de vLLM prend 0,5 chacun comme exemple. Dans cette courte vidéo, un développeur garde 2 modèles chargés sur une seule carte de 96 Go, l’un à 0,7 et l’autre à 0,2, en laissant 10 % libres :

« To serve at least one request with the model’s max seq len » : le cache KV ne tient pas

C’est l’erreur la plus « vLLM » de toutes et, une fois qu’on sait la lire, la plus utile :

ValueError: To serve at least one request with the model's max seq len (40960), (5.62 GiB KV cache is needed, which is larger than the available KV cache memory (Y GiB). Based on the available memory, the estimated maximum model length is Z. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU backend) or decreasing `max_model_len` when initializing the engine. See https://docs.vllm.ai/en/latest/configuration/conserving_memory/ for more details.

Le cache KV, c’est la mémoire où le modèle garde la conversation en cours. vLLM ne le fait pas grandir au fil de l’eau : sauf indication contraire, il le prévoit pour le contexte le plus long qu’accepte le modèle, tiré de sa propre configuration, et refuse de démarrer si une requête de cette longueur complète ne tient pas. S’il ne reste plus rien du tout après les poids, le message est plus court : No available memory for the cache blocks. Et sur un vLLM ancien, le même problème se lit ainsi : The model's max seq len (4096) is larger than the maximum number of tokens that can be stored in KV cache (3664).

La partie utile, c’est Z : vLLM a déjà calculé le contexte le plus long qui tiendrait. Utilisez-le, ou arrondissez-le vers le bas :

vllm serve Qwen/Qwen3-8B-AWQ --max-model-len 16384

Attention à la majuscule si vous utilisez un suffixe : 16K vaut 16 384, et 16k, 16 000. Avec --max-model-len auto (ou -1), vLLM choisit lui-même le contexte le plus long qui tient et l’écrit dans le journal : Auto-fit max_model_len: reduced from … to … to fit in available GPU memory (… GiB available for KV cache). Et si vous demandez plus que ce que permet le modèle, il s’arrête avec User-specified max_model_len (…) is greater than the derived max_model_len (…).

La quantité de contexte qui tient dans chaque Gio dépend de l’architecture du modèle, pas de sa taille. Nos calculs, avec la même formule que vLLM pour les couches à attention complète et un cache en 16 bits :

Modèle	Cache par token	Tokens par Gio de cache	Contexte par défaut	Cache à ce contexte
Qwen3 8B	144 Kio	7 281	40 960	5,625 Gio
Qwen3 4B 2507	144 Kio	7 281	262 144	36,0 Gio
Granite 4.2 8B	160 Kio	6 553	131 072	20,0 Gio
Qwen3 Coder 30B	96 Kio	10 922	262 144	24,0 Gio

Calculé par Local AI Scope le 15 octobre 2026 : 2 × couches × têtes KV × taille de tête × 2 octets par token, à partir de la configuration de chaque modèle, les données de notre outil de choix de modèle. Les modèles avec des couches à fenêtre glissante ou à attention linéaire suivent d’autres règles et sont laissés de côté.

PC avec RTX 3060 12 GoFiche matériel→

Autre levier : --kv-cache-dtype fp8 stocke le cache sur 8 bits au lieu de 16, soit moitié moins de mémoire par token. Cela fait gagner du contexte, et c’est un compromis que nous n’avons pas mesuré : essayez-le sur vos propres requêtes. Pour la vue d’ensemble, la conférence de vLLM lui-même à la PyTorch Conference 2025 explique comment il gère le cache KV à partir de 10:08 :

« CUDA out of memory » au chargement : les poids ne tiennent pas

Quand c’est le modèle lui-même qui est trop gros, vLLM n’arrive même pas jusqu’au cache. PyTorch s’arrête pendant le chargement :

torch.OutOfMemoryError: CUDA out of memory. Tried to allocate … GPU 0 has a total capacity of … of which … is free. …

La cause habituelle est un modèle dans son format d’origine en 16 bits. vLLM charge ces fichiers safetensors tels quels, et Qwen3 8B en BF16 occupe 15,26 Gio : sur une carte de 12 Go, il ne tient pas avant même le premier token. Les solutions, tirées du guide de vLLM pour économiser la mémoire, dans l’ordre où nous les essaierions :

• Une version quantifiée. Le même modèle en AWQ fait 5,68 Gio, et en FP8, 8,79 Gio. Cherchez ces versions sur Hugging Face, souvent publiées par les auteurs du modèle eux-mêmes.
• Moins de contexte et moins de requêtes simultanées : --max-model-len et --max-num-seqs.
• Pas de graphes CUDA : --enforce-eager s’en passe et libère leur mémoire, au prix d’un peu de vitesse.
• Plus de 1 carte : --tensor-parallel-size 2 répartit le modèle sur 2 GPU.

Un avertissement si vous venez d’Ollama : les tailles de notre outil de choix de modèle sont celles de fichiers GGUF, comme Q4_K_M, que vLLM ne charge pas d’origine. Pour vLLM, ce sont des repères, pas le même chiffre.

« Invalid repository ID », modèles à accès restreint et « trust_remote_code »

vLLM télécharge les modèles depuis Hugging Face, et 3 types de message viennent de là. Une seule faute de frappe dans le nom donne ceci, avec le Repository Not Found de Hugging Face en dessous :

ValueError: Invalid repository ID or local directory specified: 'Qwen/Qwen3-8BB'.
Please verify the following requirements:
1. Provide a valid Hugging Face repository ID.
2. Specify a local directory that contains a recognized configuration file.
   - For Hugging Face models: ensure the presence of a 'config.json'.
   - For Mistral models: ensure the presence of a 'params.json'.

Vérifiez le nom lettre par lettre. Si le nom est bon mais que le modèle vous demande d’abord d’accepter ses conditions, comme les Llama de Meta, le texte qui apparaît plus haut dans la trace est celui-ci, que nous avons obtenu en demandant Llama 3.1 8B sans être connectés :

Cannot access gated repo for url https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct/resolve/main/config.json.
Access to model meta-llama/Llama-3.1-8B-Instruct is restricted. You must have access to it and be authenticated to access it. Please log in.

Acceptez les conditions sur la page du modèle avec votre compte, puis connectez-vous une fois avec hf auth login. vLLM lit le jeton enregistré, et en accepte aussi un via --hf-token ou la variable HF_TOKEN.

Le troisième, c’est un modèle qui apporte son propre code Python. Avec la version de transformers qu’installe vLLM 0.31.0 (nous avons utilisé la 5.17.0, que la 0.32.0 accepte aussi), cela donne :

ValueError: The repository THUDM/chatglm3-6b contains custom code which must be executed to correctly load the model. You can inspect the repository content at https://hf.co/THUDM/chatglm3-6b .
 You can inspect the repository content at https://hf.co/THUDM/chatglm3-6b.
Please pass the argument `trust_remote_code=True` to allow custom code to be run.

En ligne de commande, l’interrupteur est --trust-remote-code. Et si l’architecture du modèle n’existe tout simplement pas dans vLLM, le message est Model architectures ['…'] are not supported for now. Supported architectures: …, ou, pour certaines anciennes, … was supported in vLLM until v0.23.0, and is not supported anymore. Les fichiers GGUF sont un cas à part : leur prise en charge vit désormais dans un module, vllm-gguf-plugin, que la documentation de vLLM qualifie toujours de « highly experimental ».

Port 8000 : « Address already in use » et « Engine core initialization failed »

vllm serve réserve son port avant même de démarrer le moteur : un port occupé échoue donc en quelques secondes, sans rien charger :

OSError: [Errno 98] Address already in use

Par défaut, ce port est le 8000, sur toutes les interfaces réseau. Quelque chose d’autre y écoute : un autre vLLM oublié ou n’importe quel autre serveur. Trouvez qui l’occupe, ou prenez un autre port :

ss -ltnp | grep :8000
vllm serve Qwen/Qwen3-8B-AWQ --port 8001

Le dernier message est celui que l’on colle le plus souvent en demandant de l’aide, et ce n’est pas du tout une cause :

RuntimeError: Engine core initialization failed. See root cause above. Failed core proc(s): {}

vLLM fait tourner le modèle dans un processus à part, et quand ce processus meurt au démarrage, cette ligne n’est que l’emballage. « See root cause above » veut dire exactement cela : remontez le journal jusqu’à la première erreur, et ce sera l’une de celles de cette page, très souvent celles de mémoire. Un signalement dans l’outil de suivi de vLLM montre cette ligne au-dessus d’un [Errno 98] Address already in use venu de l’un de ses processus de travail. Et une fois qu’il démarre, fermez ce qu’il ouvre sur le réseau : notre guide d’installation de vLLM explique pourquoi il écoute sur 0.0.0.0, sans clé.

Messages et valeurs par défaut tirés du code de vLLM 0.31.0 et de PyTorch 2.13.0, des guides d’installation et de mémoire de vLLM à cette étiquette, de la documentation CUDA de NVIDIA, de Hugging Face, de l’outil de suivi de vLLM et de nos propres essais avec pip, transformers 5.17.0 et huggingface_hub 1.33.0, le 15 octobre 2026. Messages de vLLM comparés de nouveau au code de la 0.32.0 le 19 octobre 2026, et le message Python de pip, le 21 octobre 2026.

Vous utilisez aussi Ollama, LM Studio ou MLX ? Leurs erreurs sont différentes, et leurs solutions aussi : Ollama ne fonctionne pas ? 9 erreurs, le message exact et la solution, LM Studio ne fonctionne pas ? 7 erreurs, le message exact et la solution et MLX ne fonctionne pas ? 7 erreurs, le message exact et la solution. Et pour savoir ce que vLLM envoie pendant que tout cela fonctionne, voyez sa fiche : vLLM : ce qu’il envoie et si vous pouvez l’auditer.