Getting started

This page walks through cloning, building, and running both ruff and ty from source.

Prerequisites

• Rust toolchain. Pinned via rust-toolchain.toml (currently MSRV 1.93, Edition 2024). rustup will fetch the right version automatically the first time you build.

• cargo-insta — needed for snapshot tests.

  cargo install cargo-insta

• uv — required to run Python utility scripts and pre-commit hooks.

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

• prek (recommended) — runs the same hooks CI does.

  uv tool install prek
  prek install

• cargo-nextest (recommended) — much faster test runner.

  cargo install cargo-nextest --locked

See CONTRIBUTING.md for the canonical contributor onboarding instructions.

Clone and build

git clone https://github.com/astral-sh/ruff.git
cd ruff
cargo build           # debug build, ~3-5 minutes on first build

Use debug builds during development. As AGENTS.md notes, "release builds lack debug assertions and have slower compile times."

Run Ruff

# Lint a file
cargo run -p ruff -- check path/to/file.py --no-cache

# Format a file
cargo run -p ruff -- format path/to/file.py

# Apply autofixes
cargo run -p ruff -- check path/to/file.py --fix

# Start the LSP server
cargo run -p ruff -- server

The CLI entry point is crates/ruff/src/main.rs, which delegates to subcommands under crates/ruff/src/commands/.

Run ty

# Type-check a file
cargo run --bin ty -- check path/to/file.py

# Start ty's language server
cargo run --bin ty -- server

ty's CLI lives at crates/ty/src/main.rs. To reproduce or minimize an ecosystem regression, use the helper script:

uv run scripts/setup_primer_project.py <project-name> <some-temp-dir>

Run the tests

The standard one-liner from AGENTS.md:

CARGO_PROFILE_DEV_OPT_LEVEL=1 \
INSTA_FORCE_PASS=1 INSTA_UPDATE=always \
CARGO_PROFILE_DEV_DEBUG="line-tables-only" \
MDTEST_UPDATE_SNAPSHOTS=1 \
cargo nextest run

Run tests for a specific crate:

cargo nextest run -p ty_python_semantic

Run a single mdtest file (paths relative to crates/ty_python_semantic/resources/mdtest):

cargo nextest run -p ty_python_semantic -- mdtest::<path/to/mdtest_file.md>

After running tests, always review the snapshot diffs before committing. See how-to-contribute/testing for details on insta, mdtest, fuzz tests, and the corpus harness.

Run lint and formatting checks

cargo clippy --workspace --all-targets --all-features -- -D warnings
RUFF_UPDATE_SCHEMA=1 cargo test
uvx prek run -a   # run all hooks (Rust + Python + Markdown formatters/linters)

Set RUFF_UPDATE_SCHEMA=1 whenever you change configuration options or rule metadata; it regenerates ruff.schema.json and ty.schema.json at the repo root. Equivalently, run cargo dev generate-all after changing CLI args, options, or rules.

Build the docs

uv run --with-requirements docs/requirements.txt mkdocs serve -f mkdocs.template.yml

The published site at https://docs.astral.sh/ruff is generated by the same mkdocs template.

Build the WASM playground

cd playground
npm install
npm run dev

The playground at https://play.ruff.rs/ wraps crates/ruff_wasm and crates/ty_wasm.

Common gotchas

• If you see INSTA_FORCE_PASS ignored, ensure you're using cargo nextest (the env var is the recommended toggle in development).
• Some snapshot tests require the right target-version Python; the harness auto-detects most cases but check the crates/*/resources/test/fixtures/ directories if a test fails locally but passes in CI.
• cargo run -p ruff and cargo run --bin ruff are equivalent.