Tooling

Build system

The build is a CMake project driven by setup.py:

File	Role
pyproject.toml	Build requirements, project metadata, ruff/mypy/typos/pytest config
setup.py	~1,100-line setuptools driver. Calls CMake, picks platform extensions, packages wheels
CMakeLists.txt	Top-level CMake. ~52 KB. Detects CUDA / ROCm / CPU and selects sources
cmake/	CMake helper modules
use_existing_torch.py	Helper that lets the build reuse an already-installed torch
requirements/	Per-platform dep lists. requirements/{build,common,cuda,rocm,cpu,tpu,xpu}/...

The CMake project produces:

• vllm/_C*.so — main C++/CUDA extension (csrc/)
• vllm/_rocm_C*.so — ROCm-specific extension when building on AMD
• vllm/_cpu_C*.so — CPU-specific extension
• vllm/_moe_C*.so, vllm/cumem_allocator*.so, etc.

For Python-only iterations, VLLM_USE_PRECOMPILED=1 skips the CMake step and links a precompiled wheel.

Pre-commit hooks

.pre-commit-config.yaml defines the canonical set of hooks. Highlights:

Hook	What it does
ruff-check, ruff-format	Linting + formatting (E, F, B, UP, SIM, I, etc.)
mypy-3.10	Static type check (run as --hook-stage manual for the full pass)
clang-format	C++/CUDA formatting against .clang-format
codespell, typos	Two complementary spell checkers
markdownlint	Doc style; config in .markdownlint.yaml
actionlint	GitHub Actions workflow validation
shellcheck	Shell scripts; respects .shellcheckrc
signoff	Requires DCO sign-off on each commit
validate-config	Checks that config dataclasses round-trip
model-registry	Ensures every architecture in the registry has a file
no-system-tests-in-benchmarks	Stops tests/ from being imported in benchmarks/
check_init_lazy_imports	Keeps vllm/__init__.py lazy
validate-pr-template	Checks the PR template stays in sync

Run all hooks:

pre-commit run --all-files

Or just one:

pre-commit run ruff-check --all-files
pre-commit run mypy-3.10 --all-files --hook-stage manual

CI

vLLM has two CI surfaces:

• Buildkite (.buildkite/) is the primary pipeline. It runs the model matrix, distributed tests, kernel benchmarks, ROCm jobs, and CPU jobs across many shards. Sharding metadata uses the split pytest marker. The pipeline definition is generated by helpers in .buildkite/scripts/.
• GitHub Actions (.github/workflows/) handles pre-commit, action validation, security scans, and the lighter PR gates.

docs/maybe_skip_pr_build.sh is used to skip CI when only docs changed.

Documentation

The user docs site lives in docs/ and is built with mkdocs-material (mkdocs.yaml, docs/.nav.yml). The site is published at https://docs.vllm.ai. Notable doc roots:

• docs/contributing/ — contributor guides (model contributions, multi-modal, attention backends, dockerfile, etc.)
• docs/design/ — design notes (PagedAttention, plug-in system, multiproc executor, V1 vs V0)
• docs/features/ — user-facing feature pages
• docs/serving/ — deployment guides
• docs/getting_started/ — install & quickstart

.readthedocs.yaml exists for legacy redirect compatibility; the canonical site is the mkdocs build.

Custom developer tools

Path	Purpose
tools/	One-off scripts: wheel size limit, registry checks, docstring linters
vllm/collect_env.py / vllm collect-env	Environment diagnostics for bug reports
vllm/scripts.py	Misc developer scripts
benchmarks/	Throughput, latency, and serving harnesses
examples/	Runnable examples used as documentation and smoke tests

Environment variables

vllm/envs.py is the single source of truth for environment overrides. Each variable is documented at its declaration site. vllm/env_override.py wraps os.environ so settings can be inspected and validated.

Frequently-touched ones during development:

Variable	Effect
VLLM_USE_PRECOMPILED	Skip the C++/CUDA build during pip install -e .
VLLM_LOGGING_LEVEL	Global log level
VLLM_WORKER_MULTIPROC_METHOD	spawn / fork / forkserver for worker processes
VLLM_TORCH_PROFILER_DIR	Where to write torch profiler traces
VLLM_DEBUG_LOG_API_SERVER_RESPONSE	Verbose HTTP response logging
VLLM_USE_RAY_V2_EXECUTOR_BACKEND	Pick RayExecutorV2 over RayDistributedExecutor
VLLM_TRACE_FUNCTION	Lightweight function-level tracing
NCCL_* / CUDA_*	Standard upstream CUDA/NCCL knobs