{"id":3539,"library":"lintrunner","title":"Lintrunner","description":"Lintrunner is a command-line tool designed to orchestrate and run various linters across polyglot projects. It centralizes linter configuration, standardizes linter invocation via a common protocol, and aggregates results for user presentation. The current version is 0.13.0, and releases appear to be on an as-needed basis rather than a fixed cadence, reflecting its active development, particularly within the Meta/PyTorch ecosystem.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/suo/lintrunner","tags":["linting","code quality","CI/CD","polyglot","developer tools"],"install":[{"cmd":"pip install lintrunner","lang":"bash","label":"Install core library"},{"cmd":"pip install lintrunner-adapters","lang":"bash","label":"Install official linter adapters (recommended)"}],"dependencies":[],"imports":[],"quickstart":{"code":"# 1. Create a .lintrunner.toml configuration file\n# Example .lintrunner.toml (save this to your project root)\n# merge_base_with = 'main'\n#\n# [[linter]]\n# name = 'EXAMPLE_LINTER'\n# include_patterns = ['**/*.py']\n# command = ['python3', '-c',\n#   'import sys; import json;\\n'\n#   'for path in sys.stdin.read().splitlines():\\n'\n#   '    with open(path) as f:\\n'\n#   '        content = f.read()\\n'\n#   '        if \"TODO\" in content:\\n'\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'\n# ]\n\n# 2. Create a dummy Python file to lint (e.g., my_file.py)\n# print(\"This is a test file.\")\n# # TODO: implement this feature\n\n# 3. Run lintrunner from your terminal in the project root:\n# pip install lintrunner\n# # For basic setup, you might need to run lintrunner init\n# # lintrunner init # This can install various linter dependencies\n# lintrunner\n\n# Expected output for my_file.py with the EXAMPLE_LINTER:\n# Path                   Line Char Code       Severity  Name          Message\n# -------------------- ------ ---- ---------- --------- ------------- ------------------------\n# my_file.py                1    1 TODO_FOUND warning   TODO check    Found a TODO in the file.","lang":"python","description":"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."},"warnings":[{"fix":"Use `lintrunner` via its command-line interface and `.lintrunner.toml` configuration. Develop custom linter adapters if integration with specific tools or logic is needed.","message":"Lintrunner 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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`).","message":"By default, `lintrunner` checks files changed in the HEAD commit or the user's working tree. Files not tracked by Git will not be linted.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Linters 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Double-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.","message":"Excluding 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.","severity":"gotcha","affected_versions":"0.13.0 and potentially earlier"},{"fix":"Always 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.","message":"Due 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.","severity":"gotcha","affected_versions":"0.13.0 and potentially earlier"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}