Cómo instalar vLLM en Linux, Windows y macOS

Para instalar vLLM en Linux con una GPU NVIDIA, cree un entorno limpio de Python 3.12 y ejecute pip install vllm, luego inicie un servidor con vllm serve Qwen/Qwen3-8B. Ese es todo el flujo recomendado. En Windows se requiere WSL2 o Docker porque vLLM solo publica wheels para Linux, y en macOS se necesita una compilación desde el código fuente que solo admite inferencia en CPU.

Antes de instalar: qué requiere realmente vLLM

Requisito	Qué funciona
Sistema operativo	Linux (x86_64 es la plataforma principal; algunas versiones también publican wheels para aarch64). Windows únicamente mediante WSL2 o Docker. macOS mediante compilación desde el código fuente.
Python	Las versiones de Python 3.9 a 3.12 cubren las versiones lanzadas hasta mediados de 2025, y la 3.13 se añade en versiones posteriores. El rango soportado varía entre versiones: consulte las notas de la versión que instale.
GPU	GPUs NVIDIA con capacidad de cómputo 7.0 o superior (V100, T4, series RTX 20 y posteriores, A10, L4, A100, H100, H200). Las tarjetas AMD requieren una compilación separada con ROCm.
CUDA	Un controlador NVIDIA actualizado. El wheel predeterminado de PyPI incluye el entorno de tiempo de ejecución CUDA necesario para la versión de PyTorch empaquetada, por lo tanto no no necesita instalar el kit de herramientas CUDA del sistema, a menos que compile vLLM desde el código fuente.
Almacenamiento en disco	El paquete en sí ocupa varios GB. Los pesos de los modelos son lo que más espacio consumen: se almacenan en ~/.cache/huggingface y van desde unos pocos GB hasta cientos de GB.

La lista oficial y continuamente actualizada se encuentra en la documentación oficial del proyecto en docs.vllm.ai, y los cambios específicos por versión se registran en la página de versiones de vLLM. Los wheels publicados y las versiones de Python compatibles se enumeran en PyPI.

Instalar vLLM en Linux con una GPU NVIDIA

Opción 1: uv (la más rápida y la que ahora recomiendan los documentos oficiales 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

El --torch-backend=auto esta bandera permite que uv detecte su controlador y seleccione una versión compatible de PyTorch/CUDA. Si su controlador es más antiguo que el requerido por el wheel, sustituya automático por un backend explícito como cu126. Las versiones disponibles de CUDA cambian con cada lanzamiento, así que consulte la página de instalación en lugar de asumir que una etiqueta específica existe.

Opción 2: pip estándar y venv

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

Opción 3: conda

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

Tenga en cuenta que vLLM debe instalarse con pip incluso dentro de un entorno conda. No instale PyTorch por separado antes: vLLM descargará automáticamente la versión exacta de torch con la que fue compilado.

Verifique la instalación

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

Si torch.cuda.is_available() muestra Falso, deténgase aquí: el problema radica en su controlador o entorno, no en vLLM, y ningún comando serve funcionará hasta que esto devuelva Verdadero.

Instalar con Docker (la opción más reproducible)

El proyecto publica una imagen oficial de servidor compatible con OpenAI. Esto evita por completo los problemas del entorno Python y es la opción recomendada en servidores compartidos o de producción:

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

El --ipc=host es crucial: vLLM utiliza memoria compartida entre procesos, y el valor predeterminado pequeño de Docker /dev/shm provoca bloqueos al usar paralelismo de tensores. Si no puede usar IPC del host, pase --shm-size=8g en su lugar. Montar la caché de Hugging Face significa que descargará cada modelo una sola vez, en lugar de una vez por contenedor. Esto requiere la instalación del NVIDIA Container Toolkit en el host.

Instalar vLLM en Windows (WSL2)

vLLM no dispone de una compilación nativa para Windows. WSL2 es la ruta oficialmente soportada y funciona bien:

1. Instale el controlador estándar de NVIDIA Windows . No instale un controlador gráfico Linux dentro de WSL: la pila CUDA de WSL se comunica a través del controlador de Windows. NVIDIA documenta este comportamiento en la guía del usuario de CUDA en WSL.
2. En PowerShell: wsl --install -d Ubuntu-24.04, y reinicie el sistema si se le solicita.
3. Dentro de Ubuntu, ejecute nvidia-smi. Si su GPU no aparece listada, resuelva ese problema antes de continuar.
4. Instalar python3.12-venv, cree un entorno virtual (venv) y siga las instrucciones para Linux indicadas anteriormente.

Dos advertencias específicas de WSL: por defecto, WSL limita la memoria RAM, así que agregue una sección [wsl2] con la línea memory= a C:\Users\\.wslconfig si la carga del modelo se interrumpe; y los pesos del modelo almacenados en el sistema de archivos de Windows (/mnt/c/...) se cargan notablemente más lentos que los pesos ubicados dentro del sistema de archivos de WSL.

Instalar vLLM en macOS

No existe una versión precompilada (wheel) para macOS en PyPI. El soporte para Apple Silicon requiere una compilación desde el código fuente exclusivamente para CPU:

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

La ruta del archivo de requisitos ha cambiado entre versiones (antes era requirements-cpu.txt en versiones anteriores), así que verifique el árbol del repositorio para la etiqueta que haya clonado. Es fundamental destacar que esta compilación no utiliza Metal ni la GPU de Apple: la inferencia se ejecuta únicamente en la CPU y es mucho más lenta que en una máquina con CUDA. El objetivo de diseño de vLLM es ofrecer servicio por lotes de alto rendimiento en GPUs de servidor, lo cual no corresponde al uso típico de una laptop Mac. Si su objetivo es ejecutar un modelo localmente en macOS, use la ruta Ollama o LM Studio, ambas compatibles con Metal.

Linux con GPUs AMD, Intel o solo CPU

ROCm (AMD), GPU/XPU de Intel y CPU x86 sin GPU tienen sus propias rutas de instalación, generalmente mediante una imagen Docker precompilada o una compilación desde el código fuente con una variable de entorno específica para el dispositivo objetivo, como VLLM_TARGET_DEVICE=cpu. Estos backends evolucionan más rápidamente que la ruta CUDA y los comandos exactos cambian entre versiones, por lo tanto, consulte siempre la página específica para su hardware en la documentación actual, en lugar de copiar comandos de tutoriales antiguos.

Iniciar el servidor y probarlo

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

Qwen3-8B es un buen primer modelo de prueba porque no tiene restricciones de acceso, se descarga rápidamente y cabe en una sola GPU de 24 GB en formato bf16. Luego realice la prueba:

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

Nota de seguridad: vllm serve se inicia sin autenticación. Pase --api-key y mantenga el puerto 8000 detrás de un cortafuegos o un proxy inverso: exponer un punto final vLLM implica una factura abierta e ilimitada por inferencias en su propio hardware.

Opciones útiles en la primera ejecución: --tensor-parallel-size N para distribuir la carga entre N GPUs, --max-model-len para limitar el contexto (el ajuste más efectivo contra errores de memoria insuficiente al iniciar), --quantization para usar puntos de control previamente cuantizados, --served-model-name para exponer un alias más corto a los clientes, y --enforce-eager para omitir la captura de gráficos CUDA cuando necesite un inicio más rápido durante la depuración.

¿Cabe el modelo? Calcule su tamaño antes de instalar

vLLM carga los pesos en formato bf16 por defecto, así que reserve aproximadamente 2 GB de VRAM por cada mil millones de parámetros, además de la caché KV —y vLLM preasigna dicha caché de forma agresiva (hasta el 90 % de la GPU con el valor predeterminado --gpu-memory-utilization). Un modelo de 8 mil millones de parámetros ocupa unos 16 GB de VRAM en bf16. Al cuantizarlo a 4 bits, el mismo modelo ocupa aproximadamente 5 GB, según lo indicado por Convly Base de datos de modelos:

Modelo	Contexto	~VRAM a 4 bits	Configuración realista en un solo nodo
Qwen3 8B	128 K	~5 GB	Una GPU de consumo de 12–24 GB
Llama 3.1 8B	128 K	~5 GB	Una GPU de consumo de 12–24 GB
Gemma 3 27B	128 K	~16 GB	Una GPU de 24 GB en cuantización de 4 bits
Qwen3 32B	128 K	~20 GB	Una tarjeta de 24 GB con cuantización de 4 bits, con poco margen disponible para la caché KV
Llama 3.3 70B	128 K	~40 GB	2× tarjetas de 24 GB con --tensor-parallel-size 2, o una tarjeta de 48 GB
DeepSeek R1	128 K	~400 GB	Servidor multi-GPU, no una estación de trabajo

Para obtener una cifra específica según su longitud de contexto y tamaño de lote, utilice la Calculadora de VRAM; el desglose detallado por modelo se encuentra en la Guía de requisitos de VRAM. Si aún está eligiendo hardware, consulte la mejoras GPUs para modelos de lenguaje local. Y antes de comprar cualquier cosa, vale la pena calcular los costos con la calculadora de autohospedaje frente a API — Llama 3.3 70B cuesta 0,10 USD de entrada / 0,32 USD de salida por cada millón de tokens en un proveedor alojado, lo cual es difícil de superar con su propia electricidad a menos que tenga una utilización sostenida bastante alta.

Errores comunes durante la instalación y el arranque de vLLM

Síntoma	Causa y solución
ImportError en vllm._C, o un error de ABI/símbolo proveniente de torch	vLLM se instaló sobre una versión incompatible de PyTorch. Elimine el entorno, créelo nuevamente desde cero e instale vLLM primero.
«La longitud máxima de secuencia del modelo es mayor que el número máximo de tokens que pueden almacenarse en la caché KV»	No hay suficiente VRAM libre para el contexto solicitado. Reduzca --max-model-len, aumente --gpu-memory-utilization, o use un punto de control cuantizado.
Memoria CUDA agotada al cargar los pesos	Los propios pesos no caben. Divídalos con --tensor-parallel-size o elija un modelo más pequeño.
No se encontró ningún controlador NVIDIA	Ninguna GPU visible para el proceso. En WSL, el controlador debe instalarse en el lado de Windows; en Docker, le falta --gpus all.
Error 401/403 al descargar un modelo	Repositorio restringido. Acepte la licencia en Hugging Face y luego autentíquese (hf auth login en versiones actuales de la CLI de Hugging Face, huggingface-cli login en versiones anteriores) o establezca HF_TOKEN.
Pausa prolongada antes de que el servidor acepte solicitudes	Normal: captura y compilación de gráficos CUDA. Use --enforce-eager para omitirla durante la depuración.

Preguntas frecuentes

¿Puedo instalar vLLM de forma nativa en Windows?

No. vLLM publica únicamente wheels para Linux, y pip install vllm en Python para Windows no le proporcionará un servidor GPU funcional. Use WSL2 con una distribución Ubuntu, o ejecute la imagen oficial de Docker. Ambas opciones están completamente soportadas y ofrecen un rendimiento casi nativo en el mismo hardware.

¿Necesito instalar primero el kit de herramientas CUDA?

No es necesario para el wheel predeterminado. Este incluye el entorno de ejecución CUDA mediante la versión fija de PyTorch que utiliza, por lo que basta con un controlador NVIDIA razonablemente actual. Solo necesitará el kit de herramientas completo con nvcc si compila vLLM desde el código fuente o construye kernels personalizados.

¿Cómo instalo una versión específica de vLLM o la compilación nocturna (nightly build)?

Fíjelo como cualquier otro paquete: pip install vllm==<versión>, eligiendo entre las versiones listadas en PyPI. Los wheels nocturnos y los correspondientes a cada commit se publican por separado por el proyecto e instalan mediante una URL adicional de índice — la dirección actual está documentada en la página de instalación, y ha cambiado anteriormente, así que léala allí en lugar de copiar un comando antiguo.

¿Por qué vLLM ocupa toda mi GPU?

Por diseño. Preasigna un grupo grande de bloques para la caché KV al iniciarse — controlado por --gpu-memory-utilization, cuyo valor predeterminado es 0,9 — porque la atención paginada es lo que permite un alto rendimiento bajo concurrencia. Reduzca este valor si necesita compartir la tarjeta y espere un menor número de solicitudes simultáneas como consecuencia.

¿Debería usar vLLM u Ollama?

Ollama es un instalador multiplataforma único orientado a un solo usuario en una sola máquina; consulte la Guía de instalación de Ollama si esta descripción le corresponde. vLLM es un motor de servicio diseñado para manejar muchas solicitudes concurrentes por GPU, con procesamiento por lotes continuo, paralelismo tensorial y una API compatible con OpenAI. Instale vLLM cuando esté sirviendo una aplicación, no cuando esté chateando localmente.

¿Qué modelo debería servir primero?

Comience con un modelo pequeño y sin restricciones para depurar la instalación y no la descarga — un modelo de clase 8B de aproximadamente 5 GB en cuantización de 4 bits es ideal. Una vez que el servidor responda a /v1/models, pase a modelos mayores. La Clasificación de modelos de lenguaje grande (LLM) es una forma razonable de seleccionar candidatos según su capacidad, precio y longitud de contexto antes de comprometer su VRAM con uno específico.