Alex Waygood
689a33fd36
## Summary Builds on #28032. Add two rules for boolean tests whose truthiness is statically known: - `redundant-condition`, enabled by default at warning severity, catches cases such as an uncalled function or method, an unawaited coroutine, a generator tested for emptiness, or a tuple whose length makes its truthiness constant. - `redundant-condition-strict`, disabled by default, covers boolean/integer conditions, conditions whose outcome is fixed only by short-circuit evaluation, and conditions containing walrus expressions. These can expose real bugs, but are also much more likely to be intentional. The checks reuse ty's truthiness inference and apply to `if`/`elif`, `while`, assertions, match guards, conditional expressions, comprehension filters, and unary `not`. The operands of `and`/`or` are checked when the expression is used as a condition. The main design question is which statically redundant tests are likely to represent mistakes. The implementation deliberately prefers missing some redundant conditions to warning about common defensive or compatibility patterns. ## Avoiding false positives ### Separate likely mistakes from more opinionated checks Types assignable to `int`, including `bool`, use the strict rule. So do conditions whose outcome is fixed by short-circuit evaluation even though their inferred value type has ambiguous truthiness, and tests containing walrus expressions. Other values with fixed truthiness use the default rule. This keeps checks of ordinary boolean/integer flags quiet by default, because these are extremely common and it is difficult to distinguish deliberately constant flags from mistakes: ```python DEBUG = False if DEBUG: # Only reported by redundant-condition-strict. print("debugging") ``` The strict rule is a sibling of the default rule: it handles a separate set of expressions rather than reporting the same expressions more aggressively. ### Distinguish a condition's outcome from its value type Short-circuit evaluation can establish a fixed outcome even when the expression's value type does not: ```python def check(value: object): if value and False: # Always false; reported by redundant-condition-strict. print("unreachable") ``` The condition fails whether `value` is truthy or falsy. However, saving `value and False` to a variable and testing that variable later is different: the saved value could be the original object, whose `__bool__` result may change between calls. The redundant-condition checks use short-circuit truthiness APIs introduced in https://github.com/astral-sh/ruff/pull/28082 for direct conditions, and value-type truthiness for tests of computed values. This also handles chained comparisons whose intermediate results are objects with mutable truthiness. ### Recognize explicitly constant tests Both rules exempt direct boolean, integer and `None` literals in the AST, such as `if False:`, `if 0:`, `while True:`, `while 1:`, and `assert None`. These spellings are strong evidence that the constant truthiness is deliberate. A name _inferred_ as `Literal[False]` is different: its value may not be apparent where it is tested, so it remains eligible for the strict rule. ### Treat walrus expressions as evidence of intentional side effects An always-truthy operand can be useful because evaluating it assigns a value: ```python if should_continue() and (message := "continuing") and is_ready(): print(message) ``` The middle operand uses the strict rule, so it does not warn by default. We does not attempt to classify arbitrary side effects. For example, `if items.append(value) or fallback:` can still trigger the default rule because `append` returns `None`. An `and`/`or` expression used to compute a value (rather than one that is used directly in an `if` test or similar), such as `result = items.append(value) or fallback`, is not flagged by either rule. ### Follow the origins of environment-dependent conditions Both rules exempt compatibility checks involving `sys.version_info`, `sys.platform`, `os.name`, and `TYPE_CHECKING`. A condition being constant for the configured environment does not make it redundant across the environments supported by the project. The exemption also follows names and attributes through their definitions, including aliases and imports across modules: ```python import sys IS_WINDOWS = sys.platform == "win32" LINE_PREFIX = "\n" if IS_WINDOWS else "" if LINE_PREFIX: # Exempt even though its truthiness is known on this platform. print(LINE_PREFIX) ``` The traversal follows assignment values, augmented assignments, walrus bindings, loop and comprehension iterables, context-manager expressions, and the subjects of captured `match` patterns. This lookup is deliberately not flow-sensitive: if any resolved definition depends on one of these symbols, the use is exempt. This is so that we err on the side of avoiding false positives. The shared definition-resolution machinery from #28032 allows this traversal during inference without requesting completed inference of the same scope. Name lookups are cached per scope and name; attribute lookups are cached per receiver type and attribute name. Definition traversal has its own Salsa query boundary and handles cyclic aliases, so repeated conditions can share the provenance analysis. ### Preserve defensive assertions and exhaustive dispatch Defensive boolean/integer assertions such as `assert isinstance(value, int)` remain useful at runtime even when `value` is annotated as `int`, since the runtime does not enforce type annotations. These are therefore exempt from both rules. Non-boolean mistakes such as `assert function` (where the user meant `assert function()`) are still reported by the default rule. A complete assertion whose value type has ambiguous truthiness but whose outcome is fixed by short-circuit evaluation remains eligible for the strict rule. For `if` and `elif` statements, the strict rule also recognizes defensive exits. An always-false condition is exempt when its body ends in a `raise`, an assertion that might fail, a call returning `Never`, or a return assignable to `NotImplementedType`: ```python def increment(value: int) -> int: if not isinstance(value, int): raise TypeError("expected an int") return value + 1 ``` For an always-true condition, the same heuristic examines an immediately following `else` suite, or the remainder of the surrounding suite when there are no later clauses. This accommodates exhaustive dispatch followed by `assert_never`, and early-return dispatch followed by a defensive exception. These defensive-exit exemptions apply to boolean/integer conditions and conditions requiring short-circuit analysis. An uncalled function is still suspicious even when an otherwise unreachable branch raises. ### Check compound conditions once In `result = flag and function`, Python does not test the truthiness of the final operand: it simply returns that value if evaluation reaches it. The rule therefore does not flag `function`, even though it is an always-truthy object in a boolean expression. In `if flag and predicate:`, the surrounding `if` does test the truthiness of `predicate`, so the rule reports the uncalled function even though the complete condition has ambiguous truthiness. Unlike `and`/`or` expressions used to compute values, `not` explicitly tests its operand's truthiness even when it used to computer a value, so `not` expressions are checked even outside the context of `if`/`while`/`elif`/`assert` tests. For compound conditions, the redundant-condition checks visit operands before deciding whether to report the complete expression. Reporting an uncalled function in `if not function:` suppresses a second duplicate diagnostic on the `not function` expression as a whole. Boolean/integer operands and operands requiring short-circuit analysis are instead suppressed so that the complete condition can be reported once. This applies consistently to statement conditions, conditional expressions, and comprehension filters. Boolean tests inside value expressions, such as `if consume(not function):`, are checked independently. Tests in nested scopes are checked when those scopes are inferred. Neither rule runs in stub files or files excluded from checking. Diagnostic and provenance analysis is skipped entirely when both rules are disabled. ## Diagnostics and fixes Special-case diagnostics are provided to help explain some of the more common errors we see in the ecosystem: an uncalled function or method being always truthy, a fixed-length tuple being always truthy or always falsy, a `TypedDict` always being truthy due to the presence of `Required` fields, a `@final` class without `__bool__` or `__len__` being always truthy, or an unevaluated generator being always truthy. For simple function and method references, the diagnostic carries a call fix. A parameterless signature gets an unsafe `()` fix; signatures with parameters get a display-only `(...)` suggestion. Generator diagnostics suggest `any()` and carry a display-only wrapping fix when the standard `any` builtin is known not to be shadowed, including by a custom `__builtins__.pyi`. These fixes are deliberately not classified as safe: calling a function or consuming a generator can change runtime behavior, and the intended correction may be different. ### Default-rule diagnostics <details> <summary>Uncalled function</summary>  </details> <details> <summary>Uncalled method</summary>  </details> <details> <summary>Generator: suggest <code>any()</code></summary>  </details> <details> <summary>Tuple with a fixed length</summary>  </details> <details> <summary>Tuple with a minimum length</summary>  </details> <details> <summary>Empty tuple</summary>  </details> <details> <summary>Nonempty string literals</summary>  </details> <details> <summary>Empty string</summary>  </details> <details> <summary><code>None</code></summary>  </details> <details> <summary><code>TypedDict</code>: required fields and their declarations</summary>  </details> <details> <summary>Final class without <code>__bool__</code> or <code>__len__</code></summary>  </details> <details> <summary>Enum: implicit finality</summary>  </details> ### Strict-rule diagnostics These examples enable `redundant-condition-strict` explicitly. <details> <summary>Indexing <code>bytes</code> returns <code>int</code></summary>  </details> <details> <summary>Comparing <code>str</code> with <code>bytes</code></summary>  </details> <details> <summary>Length comparison: explain the fixed tuple length</summary>  </details> <details> <summary>Comparison: omit an obvious literal's type annotation</summary>  </details> ## Implementation The semantic index records the outermost boolean tests in each scope, so one check owns the diagnostics for a complete condition and its subexpressions. A shared checker separates classification, context exemptions, and duplicate suppression from diagnostic rendering. The main implementation is in `types/infer/builder/redundant_conditions/mod.rs`; its `diagnostic.rs` submodule constructs messages and fixes, and `exemptions.rs` handles environment provenance and defensive exits.
Ruff
An extremely fast Python linter and code formatter, written in Rust.
Linting the CPython codebase from scratch.
- ⚡️ 10-100x faster than existing linters (like Flake8) and formatters (like Black)
- 🐍 Installable via
pip - 🛠️
pyproject.tomlsupport - 🤝 Python 3.14 compatibility
- ⚖️ Drop-in parity with Flake8, isort, and Black
- 📦 Built-in caching, to avoid re-analyzing unchanged files
- 🔧 Fix support, for automatic error correction (e.g., automatically remove unused imports)
- 📏 Over 900 built-in rules, with native re-implementations of popular Flake8 plugins, like flake8-bugbear
- ⌨️ First-party editor integrations for VS Code and more
- 🌎 Monorepo-friendly, with hierarchical and cascading configuration
Ruff aims to be orders of magnitude faster than alternative tools while integrating more functionality behind a single, common interface.
Ruff can be used to replace Flake8 (plus dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake, and more, all while executing tens or hundreds of times faster than any individual tool.
Ruff is extremely actively developed and used in major open-source projects like:
...and many more.
Ruff is backed by Astral, the creators of uv and ty.
Read the launch post, or the original project announcement.
Testimonials
Sebastián Ramírez, creator of FastAPI:
Ruff is so fast that sometimes I add an intentional bug in the code just to confirm it's actually running and checking the code.
Nick Schrock, founder of Elementl, co-creator of GraphQL:
Why is Ruff a gamechanger? Primarily because it is nearly 1000x faster. Literally. Not a typo. On our largest module (dagster itself, 250k LOC) pylint takes about 2.5 minutes, parallelized across 4 cores on my M1. Running ruff against our entire codebase takes .4 seconds.
Bryan Van de Ven, co-creator of Bokeh, original author of Conda:
Ruff is ~150-200x faster than flake8 on my machine, scanning the whole repo takes ~0.2s instead of ~20s. This is an enormous quality of life improvement for local dev. It's fast enough that I added it as an actual commit hook, which is terrific.
Timothy Crosley, creator of isort:
Just switched my first project to Ruff. Only one downside so far: it's so fast I couldn't believe it was working till I intentionally introduced some errors.
Tim Abbott, lead developer of Zulip (also here):
This is just ridiculously fast...
ruffis amazing.
Table of Contents
For more, see the documentation.
Getting Started
For more, see the documentation.
Installation
Ruff is available as ruff on PyPI.
Invoke Ruff directly with uvx:
uvx ruff@0.16.6 check # Lint all files in the current directory.
uvx ruff@0.16.6 format # Format all files in the current directory.
Or install Ruff with uv (recommended), pip, or pipx:
# With uv.
uv tool install ruff@latest # Install Ruff globally.
uv add --dev ruff # Or add Ruff to your project.
# With pip.
pip install ruff
# With pipx.
pipx install ruff
Starting with version 0.5.0, Ruff can be installed with our standalone installers:
# On macOS and Linux.
curl -LsSf https://astral.sh/ruff/install.sh | sh
# On Windows.
powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"
# For a specific version.
curl -LsSf https://astral.sh/ruff/0.16.6/install.sh | sh
powershell -c "irm https://astral.sh/ruff/0.16.6/install.ps1 | iex"
You can also install Ruff via Homebrew, Conda, and with a variety of other package managers.
Usage
To run Ruff as a linter, try any of the following:
ruff check # Lint all files in the current directory (and any subdirectories).
ruff check path/to/code/ # Lint all files in `/path/to/code` (and any subdirectories).
ruff check path/to/code/*.py # Lint all `.py` files in `/path/to/code`.
ruff check path/to/code/to/file.py # Lint `file.py`.
ruff check @arguments.txt # Lint using an input file, treating its contents as newline-delimited command-line arguments.
Or, to run Ruff as a formatter:
ruff format # Format all files in the current directory (and any subdirectories).
ruff format path/to/code/ # Format all files in `/path/to/code` (and any subdirectories).
ruff format path/to/code/*.py # Format all `.py` files in `/path/to/code`.
ruff format path/to/code/to/file.py # Format `file.py`.
ruff format @arguments.txt # Format using an input file, treating its contents as newline-delimited command-line arguments.
Ruff can also be used as a pre-commit hook via ruff-pre-commit:
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.16.6
hooks:
# Run the linter.
- id: ruff-check
args: [ --fix ]
# Run the formatter.
- id: ruff-format
Ruff can also be used as a VS Code extension or with various other editors.
Ruff can also be used as a GitHub Action via
ruff-action:
name: Ruff
on: [ push, pull_request ]
jobs:
ruff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/ruff-action@v3
Configuration
Ruff can be configured through a pyproject.toml, ruff.toml, or .ruff.toml file (see:
Configuration, or Settings
for a complete list of all configuration options).
For the complete list of enabled rules, see Default Rules.
If left unspecified, Ruff's default configuration is equivalent to the following ruff.toml file:
# Exclude a variety of commonly ignored directories.
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".git-rewrite",
".hg",
".ipynb_checkpoints",
".mypy_cache",
".nox",
".pants.d",
".pyenv",
".pytest_cache",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
".vscode",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"site-packages",
"venv",
]
# Same as Black.
line-length = 88
indent-width = 4
# Assume Python 3.10
target-version = "py310"
[lint]
# select = [...] # See the Default Rules page for the full listing.
ignore = []
# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []
# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
[format]
# Like Black, use double quotes for strings.
quote-style = "double"
# Like Black, indent with spaces, rather than tabs.
indent-style = "space"
# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false
# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"
Note that, in a pyproject.toml, each section header should be prefixed with tool.ruff. For
example, [lint] should be replaced with [tool.ruff.lint].
Some configuration options can be provided via dedicated command-line arguments, such as those related to rule enablement and disablement, file discovery, and logging level:
ruff check --select F401 --select F403 --quiet
The remaining configuration options can be provided through a catch-all --config argument:
ruff check --config "lint.per-file-ignores = {'some_file.py' = ['F841']}"
To opt in to the latest lint rules, formatter style changes, interface updates, and more, enable
preview mode by setting preview = true in your configuration
file or passing --preview on the command line. Preview mode enables a collection of unstable
features that may change prior to stabilization.
See ruff help for more on Ruff's top-level commands, or ruff help check and ruff help format
for more on the linting and formatting commands, respectively.
Rules
Ruff supports over 900 lint rules, many of which are inspired by popular tools like Flake8, isort, pyupgrade, and others. Regardless of the rule's origin, Ruff re-implements every rule in Rust as a first-party feature.
By default, Ruff enables rules from the F, E, B, UP, and RUF categories,
as well as many more, omitting any stylistic rules that overlap with the use of a formatter, like
ruff format or Black.
If you're just getting started with Ruff, the default rule set is a great place to start: it catches a wide variety of common errors (like unused imports) with zero configuration. See Default Rules for the complete list.
Beyond the defaults, Ruff re-implements some of the most popular Flake8 plugins and related code quality tools, including:
- autoflake
- eradicate
- flake8-2020
- flake8-annotations
- flake8-async
- flake8-bandit (#1646)
- flake8-blind-except
- flake8-boolean-trap
- flake8-bugbear
- flake8-builtins
- flake8-commas
- flake8-comprehensions
- flake8-copyright
- flake8-datetimez
- flake8-debugger
- flake8-django
- flake8-docstrings
- flake8-eradicate
- flake8-errmsg
- flake8-executable
- flake8-future-annotations
- flake8-gettext
- flake8-implicit-str-concat
- flake8-import-conventions
- flake8-logging
- flake8-logging-format
- flake8-no-pep420
- flake8-pie
- flake8-print
- flake8-pyi
- flake8-pytest-style
- flake8-quotes
- flake8-raise
- flake8-return
- flake8-self
- flake8-simplify
- flake8-slots
- flake8-super
- flake8-tidy-imports
- flake8-todos
- flake8-type-checking
- flake8-use-pathlib
- flynt (#2102)
- isort
- mccabe
- pandas-vet
- pep8-naming
- pydocstyle
- pygrep-hooks
- pylint-airflow
- pyupgrade
- tryceratops
- yesqa
For a complete enumeration of the supported rules, see Rules.
Contributing
Contributions are welcome and highly appreciated. To get started, check out the contributing guidelines.
You can also join us on Discord.
Support
Having trouble? Check out the existing issues on GitHub, or feel free to open a new one.
You can also ask for help on Discord.
Acknowledgements
Ruff's linter draws on both the APIs and implementation details of many other tools in the Python ecosystem, especially Flake8, Pyflakes, pycodestyle, pydocstyle, pyupgrade, and isort.
In some cases, Ruff includes a "direct" Rust port of the corresponding tool. We're grateful to the maintainers of these tools for their work, and for all the value they've provided to the Python community.
Ruff's formatter is built on a fork of Rome's rome_formatter,
and again draws on both API and implementation details from Rome,
Prettier, and Black.
Ruff's import resolver is based on the import resolution algorithm from Pyright.
Ruff is also influenced by a number of tools outside the Python ecosystem, like Clippy and ESLint.
Ruff is the beneficiary of a large number of contributors.
Ruff is released under the MIT license.
Who's Using Ruff?
Ruff is used by a number of major open-source projects and companies, including:
- Albumentations
- Amazon (AWS SAM)
- Anki
- Anthropic (Python SDK)
- Apache Airflow
- AstraZeneca (Magnus)
- Babel
- Benchling (Refac)
- Bokeh
- Capital One (datacompy)
- CrowdCent (NumerBlox)
- Cryptography (PyCA)
- CERN (Indico)
- DVC
- Dagger
- Dagster
- Databricks (MLflow)
- Dify
- FastAPI
- Godot
- Gradio
- Great Expectations
- HTTPX
- Hatch
- Home Assistant
- Hugging Face (Transformers, Datasets, Diffusers)
- IBM (Qiskit)
- ING Bank (popmon, probatus)
- Ibis
- ivy
- JAX
- Jupyter
- Kraken Tech
- LangChain
- Litestar
- LlamaIndex
- Matrix (Synapse)
- MegaLinter
- Meltano (Meltano CLI, Singer SDK)
- Microsoft (Semantic Kernel, ONNX Runtime, LightGBM)
- Modern Treasury (Python SDK)
- Mozilla (Firefox)
- Mypy
- Nautobot
- Netflix (Dispatch)
- Neon
- Nokia
- NoneBot
- NumPyro
- ONNX
- OpenBB
- Open Wine Components
- PDM
- PaddlePaddle
- Pandas
- Pillow
- Poetry
- Polars
- PostHog
- Prefect (Python SDK, Marvin)
- PyInstaller
- PyMC
- PyMC-Marketing
- pytest
- PyTorch
- Pydantic
- Pylint
- PyScripter
- PyVista
- Reflex
- River
- Rippling
- Robyn
- Saleor
- Scale AI (Launch SDK)
- SciPy
- Snowflake (SnowCLI)
- Sphinx
- Stable Baselines3
- Starlette
- Streamlit
- The Algorithms
- Vega-Altair
- Weblate
- WordPress (Openverse)
- ZenML
- Zulip
- build (PyPA)
- cibuildwheel (PyPA)
- delta-rs
- featuretools
- meson-python
- nox
- pip
Show Your Support
If you're using Ruff, consider adding the Ruff badge to your project's README.md:
[](https://github.com/astral-sh/ruff)
...or README.rst:
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:target: https://github.com/astral-sh/ruff
:alt: Ruff
...or, as HTML:
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="max-width:100%;"></a>
License
This repository is licensed under the MIT License
