lintrunner

What it is and what it does

Lintrunner is a polyglot linting orchestrator that runs multiple linters on a codebase with a unified configuration and output format. It determines which files need linting (by default, files changed in HEAD and the working tree), invokes each linter via a common protocol, and collects their results into a single report. The tool is designed for large projects with mixed languages and tooling—you configure linters once in a .lintrunner.toml file, and lintrunner handles parallelization, path selection, and result aggregation.

The package has no runtime dependencies and ships as a compiled binary (Rust implementation) with wheels for macOS, Linux, Windows, and RISC-V. It expects each linter to be wrapped in an adapter that outputs JSON Lines to stdout and respects a {{PATHSFILE}} placeholder for the list of paths to check. Git integration is built in: by default it lints only changed files, but you can override this with --all-files, --revision, --merge-base-with, or by passing paths directly.

Use it for:

• Enforce consistent code style across a monorepo with multiple languages using a single lintrunner command.
• Integrate linting into CI/CD pipelines with selective linter runs (--take, --skip) to balance thoroughness and speed.
• Adopt linting incrementally on an existing project by using --output oneline to navigate through lint messages.
• Run linters only on changed files in a pull request using --merge-base-with to avoid re-linting the entire codebase.
• Combine project-wide and local linter configs via multiple .lintrunner.toml files (e.g., lintrunner.toml and lintrunner.private.toml).

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Lintrunner orchestrates and runs multiple linters across a codebase, deciding which files need linting, invoking linters via a common protocol, and aggregating their results.

Yes, if you manage a polyglot codebase and want unified linter orchestration. Lintrunner is actively maintained with no external runtime dependencies and ships as a compiled binary with broad platform support. The main gotcha is the unclear license—verify it fits your project's constraints before committing. The learning curve is moderate: you must write linter adapters to implement the JSON Lines protocol, but the tool itself is straightforward to configure and use.

Install

lintrunner on PyPI

pip install lintrunner

uv add lintrunner

poetry add lintrunner

Installing lintrunner

Before you install

Medium install friction due to platform-specific wheels and Rust compilation. Active maintenance with recent releases; last commit 2026-05-10 and monthly downloads in the millions suggest stable, widely-used tooling.

License in practice

License status is unclear—no SPDX identifier or raw license text provided. Verify the actual license terms in the repository before adopting in proprietary or restricted-license projects.

Quickstart

pip install lintrunner

Create .lintrunner.toml with linter configurations, then:
lintrunner  # lints HEAD and working tree changes
lintrunner --all-files  # lints all configured paths
lintrunner foo.py bar.cpp  # lint specific files

Requires Python >=3.6 and git for change detection. Linters must be configured in .lintrunner.toml and implement lintrunner's protocol (JSON Lines output to stdout).

Verify before relying

• Whether the unclear license is permissive, copyleft, or proprietary—check the repository for actual license file.
• Whether Rust compilation is required at install time or if pre-built wheels cover all target platforms.
• Performance characteristics when linting very large codebases or with many linters configured.

Package facts

Evidence: lintrunner-0.13.1-py3-none-macosx_10_12_x86_64.whl; lintrunner-0.13.1-py3-none-macosx_11_0_arm64.whl; lintrunner-0.13.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; lintrunner-0.13.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; lintrunner-0.13.1-py3-none-manylinux_2_31_riscv64.whl; lintrunner-0.13.1-py3-none-win32.whl; lintrunner-0.13.1-py3-none-win_amd64.whl

Tags

More Quality Assurance packages