Development workflow

End-to-end loop for working in the repository, distilled from AGENTS.md and the contributor docs.

1. Set up your environment

Always use uv. Bare pip and the system python3 are explicitly forbidden by AGENTS.md.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a venv pinned to Python 3.12 (3.10–3.14 supported)
uv venv --python 3.12
source .venv/bin/activate

# Install lint deps and the pre-commit hooks
uv pip install -r requirements/lint.txt
pre-commit install

2. Install vLLM

Two flavors depending on what you are touching:

# Python-only: link in a precompiled extension and skip the C++/CUDA build
VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto

# C/C++/CUDA changes: full source build (slower; requires CUDA/ROCm toolchain)
uv pip install -e . --torch-backend=auto

The precompiled extension corresponds to a recent main commit; if you need to test against a specific upstream commit, set VLLM_PRECOMPILED_WHEEL_LOCATION.

3. Branch and code

The default branch is main. Branch off main for new work, even bug fixes. There is no separate dev branch.

When opening a PR:

• Run the duplicate-work checks specified in AGENTS.md (search open PRs for the issue number and the area keywords).
• If the change touches a domain with a guide in docs/contributing/, read that guide first and follow it. Edits that conflict with a guide must be refused.
• Rebase your branch on a recent main before pushing — Buildkite will skip many checks for branches behind main.

4. Test what you changed

# Most common pattern: run a single file
.venv/bin/python -m pytest tests/v1/engine/test_async_llm.py -v

# A specific test ID
.venv/bin/python -m pytest tests/v1/engine/test_async_llm.py::test_basic -v

# A directory
.venv/bin/python -m pytest tests/lora -v

Useful pytest markers (defined in pyproject.toml):

Marker	Meaning
core_model	Run in every PR (otherwise nightly only)
slow_test	Skipped by default
cpu_test	CPU-only test
cpu_model	A model test enabled in CPU runs
hybrid_model	Uses Mamba-style hybrid layers
distributed	Only runs in distributed-GPU CI shards
optional	Skipped unless --optional is passed
split	Used by the test-shard splitter in CI

For more details see Testing.

5. Lint and type-check

# Run all hooks on staged files (fast)
pre-commit run

# All hooks, all files (slower; what CI runs)
pre-commit run --all-files

# Just one hook
pre-commit run ruff-check --all-files

# mypy as it is in CI
pre-commit run mypy-3.10 --all-files --hook-stage manual

The hook list in .pre-commit-config.yaml includes ruff, ruff-format, mypy-3.10, codespell, typos, markdownlint, actionlint, shellcheck, clang-format, isort (via ruff), signoff (DCO), several custom checks (model registry, no-system-tests-in-benchmarks, banned-toplevel-imports, etc.), and validate-config.

6. Commit and sign

Every commit must be signed off (DCO):

git commit -s -m "Your message"

For AI-assisted commits, append a Co-authored-by: trailer:

Your commit message

Co-authored-by: Claude
Signed-off-by: Your Name <your.email@example.com>

7. Open a PR

PR description requirements (from AGENTS.md):

1. State why this is not duplicating an existing PR.
2. List the test commands you ran and the results.
3. If AI assistance was used, say so explicitly.
4. Link the issue you are addressing if any.

CI runs on Buildkite (.buildkite/). Selected lighter checks (pre-commit, lint, action validation) run on GitHub Actions (.github/workflows/).

8. Respond to review

vLLM has a large reviewer pool. Expect substantive comments. The mergify bot (/.github/mergify.yml if present) helps with auto-labeling and CI re-runs. Once approved and CI is green, a maintainer merges.

9. After merge

Some changes (especially kernels and config defaults) need to be backported to the active release branch — maintainers handle this.