vLLM on a Mac: pip Has No Wheel, Metal Comes From a Plugin
pip install vllm on an Apple silicon Mac fails on CUDA_HOME, and every guide that says otherwise was written for Linux.
📜 Table of Contents
Three routes exist and they are not interchangeable. pip install vllm does not work on a Mac at all: the 0.34.0 release on PyPI ships two wheels, both Linux. The official CPU build is source-only and runs on the CPU. Anything Metal goes through a plugin that a maintainer spun up in December 2025.
Every command and number below comes from the project's own documentation, its PyPI files and its issue tracker, read on 21 November 2026. No Mac was used to write this, so there are no throughput numbers here, only what each path installs and what it supports.
The three paths, side by side
| path | what you install | compute | prebuilt? | macOS floor |
|---|---|---|---|---|
| pip install vllm | nothing usable | none | no macOS wheel exists | n/a |
| CPU build from source | vLLM 0.34.0, compiled locally | CPU, FP32 and FP16 | no wheel, no image | Sonoma |
| vLLM Metal plugin | vllm-metal, prebuilt wheels | GPU via MLX | brew tap or install script | 15 or later |
Path 1: why pip install vllm fails on a Mac
Look at the files attached to vllm 0.34.0 on PyPI: vllm-0.34.0-cp38-abi3-manylinux_2_28_x86_64.whl at 228.0 MB, vllm-0.34.0-cp38-abi3-manylinux_2_28_aarch64.whl at 227.9 MB, and a 48.5 MB source tarball. There is no macosx tag anywhere, so pip falls back to the sdist and tries to compile against CUDA.
That failure is documented in the tracker since 2023: issue #1441, opened 21 October 2023, reports RuntimeError: Cannot find CUDA_HOME. CUDA must be available to build the package after a plain pip install vllm on a Mac. The issue was closed a day later, and the answer has not changed in the three years since: there is no GPU build for macOS through pip.
Path 2: the official CPU build, which does exist
The vLLM docs now carry an Apple silicon page, and it is blunt about the status: experimental support for macOS, users must build from source, and the CPU implementation supports FP32 and FP16 only. Requirements are macOS Sonoma or later, Xcode 15.4 or later with Command Line Tools, and Apple Clang 15.0.0 or newer. There are no prebuilt Apple silicon wheels and no prebuilt images.
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -r requirements/cpu.txt
uv pip install -e .
On macOS VLLM_TARGET_DEVICE is set to cpu automatically, which is also the only device that build supports. The docs list two build failures worth knowing about before you start. Missing standard headers such as 'map' file not found means a broken Command Line Tools install, fixed by reinstalling them. Errors like 'constexpr' is not a type mean the build defaulted to an older C++ standard, fixed by adding set(CMAKE_CXX_STANDARD 17) in cmake/cpu_extension.cmake. The macOS CPU build is smoke-tested in CI on the latest Apple silicon runner; other macOS and Clang versions are best-effort.
What you get for that compile: vLLM's scheduler, paged attention and OpenAI-compatible server, running on CPU. On a laptop that is a correctness environment, not a serving environment. Nothing in the docs promises a token rate.
Path 3: vLLM Metal, the plugin that came out of the MPS request
Issue #29629, "vLLM with MPS Support", opened 27 November 2025 and asked for exactly this. On 12 December 2025 a maintainer answered that future hardware backends should go through the plugin interface, and that he had created the vllm-project/vllm-metal repository to build it there. The issue closed on 17 December 2025.
That plugin is now the Metal route. It is Apache-2.0, has 2,008 stars, and was last pushed on 20 November 2026, so it is actively maintained rather than abandoned. It uses MLX as the compute backend and keeps vLLM's engine, scheduler and OpenAI-compatible API on top.
brew tap vllm-project/vllm-metal https://github.com/vllm-project/vllm-metal
brew install vllm-project/vllm-metal/vllm-metal
The install script is the other route, and it is what the project's own recipes assume:
curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
source ~/.venv-vllm-metal/bin/activate
Two constraints are stated in the installation doc and easy to miss. It requires Apple Silicon and macOS 15 or later, and pip install vllm-metal is explicitly not supported. Both install paths default to Python 3.12 with prebuilt wheels and need no compiler. If you want the stable release through the script rather than the development build, append bash -s -- --stable.
The only sizing numbers the project publishes
The recipes are organised by Mac memory, and they choose the model for you. This is the closest thing to a supported-hardware list:
| Mac memory | model served | first download | max-model-len | max-num-batched-tokens |
|---|---|---|---|---|
| 16 GB | Qwen3.5-9B-MLX-4bit | 6.0 GB | 8192 | 2048 |
| 32 GB | Qwen3.5-27B-4bit | 16 GB | 32768 | 1024 |
| 64 GB | Qwen3.5-35B-A3B-4bit | 20 GB | 32768 | not set |
The notes attached to those rows are the useful part. On 16 GB, "without it this model does not fit" refers to --max-num-batched-tokens 2048, which reads long text in smaller steps to lower peak memory. On 32 GB, the 27B model fits a 32k window but the doc warns it is slow to read long text and suggests the 9B model for faster replies. Both point at the same trade: on a Mac, context length and reply speed come out of the same memory pool that the rest of your desktop is using.
Which path to take
If the goal is to run vLLM's API and scheduler locally against a real model on the GPU, the plugin is the only route, and the brew tap is the shortest install in the docs. If the goal is maximum tokens per second on a Mac, this is not the tool: llama.cpp and MLX are the direct engines, and vLLM Metal is a wrapper over MLX anyway. If the goal is a test harness for code that will eventually run on CUDA, the CPU build is the faithful one, at CPU speed.
For the CUDA side of the same engine, the deployment steps are in the vLLM deploy guide, and the engine comparison with Ollama and TGI is in vLLM vs Ollama vs TGI. How much memory the cache itself needs, per model and per context length, is in the KV cache sizing tables.
What this article does not tell you
No throughput, latency or memory figure here was measured. The recipes give model, context and batching flags but publish no token rates, and inventing a comparison between an M-series laptop and an H100 would be the kind of number that gets repeated for years and was never true. Install one path, run your own prompt set, and compare against the engine you were already using.
Written by our editorial team; tools listed here are tested or verified against public sources. Links point to official sites or GitHub repos for reference only — no paid placements.