Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
To get started with `lintrunner`, first install the tool. Then, create a `.lintrunner.toml` file in your project's root directory to define the linters and their rules. `lintrunner` primarily operates as a command-line tool, checking files that have changed in your working tree or HEAD commit by default. You can use `lintrunner init` for an initial setup that may install additional linter dependencies. For linters that aren't Python-based, `lintrunner` uses 'adapter' scripts to conform to its standard JSON Lines output protocol.
# 1. Create a .lintrunner.toml configuration file
# Example .lintrunner.toml (save this to your project root)
# merge_base_with = 'main'
#
# [[linter]]
# name = 'EXAMPLE_LINTER'
# include_patterns = ['**/*.py']
# command = ['python3', '-c',
# 'import sys; import json;\n'
# 'for path in sys.stdin.read().splitlines():\n'
# ' with open(path) as f:\n'
# ' content = f.read()\n'
# ' if "TODO" in content:\n'
# ' print(json.dumps({"path": path, "line": 1, "char": 1, "code": "TODO_FOUND", "severity": "warning", "name": "TODO check", "message": "Found a TODO in the file."}))\n'
# ]
# 2. Create a dummy Python file to lint (e.g., my_file.py)
# print("This is a test file.")
# # TODO: implement this feature
# 3. Run lintrunner from your terminal in the project root:
# pip install lintrunner
# # For basic setup, you might need to run lintrunner init
# # lintrunner init # This can install various linter dependencies
# lintrunner
# Expected output for my_file.py with the EXAMPLE_LINTER:
# Path Line Char Code Severity Name Message
# -------------------- ------ ---- ---------- --------- ------------- ------------------------
# my_file.py 1 1 TODO_FOUND warning TODO check Found a TODO in the file.
lintrunner --version
Debug
Known issues
gotchaLintrunner primarily functions as a command-line tool. While you can write custom linter adapters in Python that adhere to its JSON Lines output protocol, direct programmatic import of `lintrunner` as a library for general linting within Python code is not its primary use case. Its internal components are not designed for public API consumption.fixUse `lintrunner` via its command-line interface and `.lintrunner.toml` configuration. Develop custom linter adapters if integration with specific tools or logic is needed.
affects: All versions
gotchaBy default, `lintrunner` checks files changed in the HEAD commit or the user's working tree. Files not tracked by Git will not be linted.fixEnsure all relevant files are tracked by Git (`git add <file>`). To lint all files, use `lintrunner --all-files`. To lint specific paths, pass them as arguments (e.g., `lintrunner foo.py bar.cpp`).
affects: All versions
breakingLinters invoked by `lintrunner` are expected to exit with code 0, even if lint errors are reported. A non-zero exit code from a linter is treated by `lintrunner` as a 'general linter failure', indicating an issue with the linter's implementation of the protocol, rather than reported lint messages.fixEnsure custom linter adapters (or the underlying linters they wrap) always exit successfully (code 0) and report any linting issues as `LintMessage` JSON Lines to stdout.
affects: All versions
gotchaExcluding patterns in `.lintrunner.toml` might not always work as expected, especially with newly added files or complex globbing. Issues have been reported where `exclude_patterns` are ignored.fixDouble-check `include_patterns` and `exclude_patterns` syntax. If issues persist, consider more specific path arguments or adjusting the linter's command itself to filter paths. Monitor GitHub issues for updates on specific exclusion bugs.
affects: 0.13.0 and potentially earlier
gotchaDue to its incremental linting approach, `lintrunner` might occasionally suggest unexpected or 'destructive' changes, especially when interacting with linters that are sensitive to partial file inputs.fixAlways review suggested changes carefully. If unexpected behavior occurs, try running the linter directly on the full file or codebase to isolate if the issue lies with the linter or `lintrunner`'s incremental invocation.
affects: 0.13.0 and potentially earlier
Errors
Common errors & fixes
ERROR: Unsupported platform: Windows/Windows-Intel64
Lintrunner does not support Windows platforms.
fixUse Lintrunner on a supported platform, such as Linux or macOS.
ImportError: cannot import name 'appdirs' from 'pkg_resources.extern'
The 'appdirs' module is deprecated and may not be compatible with the current environment.
fixEnsure that 'setuptools' is up to date and consider replacing 'appdirs' with 'platformdirs'.
Lintrunner changes mypy config somehow, type checks likely broken
Running Lintrunner may alter mypy configurations, leading to incorrect type check results.
fixReview and restore the original mypy configuration after running Lintrunner.
error: subprocess-exited-with-error × Preparing metadata (pyproject.toml) did not run successfully. │ exit code: 1 ╰─> [6 lines of output] Cargo, the Rust package manager, is not installed or is not on PATH.
Lintrunner, or one of its dependencies, requires the Rust compiler and its package manager, Cargo, to be installed and available in the system's PATH during the installation process.
fixInstall Rust and Cargo by following the instructions on https://rustup.rs/ before attempting to install lintrunner via pip.
ERROR: Unsupported platform: Windows/Windows-Intel64.
The `lintrunner init` command, or specific linters it tries to set up, may not fully support Windows platforms, leading to this explicit error during initialization.
fixCheck the lintrunner documentation for official Windows support and any workarounds or alternative setup instructions; generally, lintrunner is heavily used in Linux/macOS environments, and Windows support might be limited for certain features or linters.
Upgrade
Version history
0.13.0latest on PyPI · released Jan 24, 2026
Audit
Dependencies
No dependency data recorded yet.