ruff --preview: Opt Into Preview Rules
ruff --preview turns on rules, fixes, and formatter changes that are still unstable and may change between releases.
Preview is Ruff's opt-in channel for not-yet-stable work. It is where new rules land before they are promoted, which makes it powerful but volatile.
What it does
Preview mode enables rules and behavior that Ruff has not yet stabilized. Some rules only exist in preview and cannot be selected without it. Enable it with --preview or preview = true under [tool.ruff]. Preview rules and their fixes can change or be renamed between Ruff releases.
Common usage
ruff check --preview .
# or in config
[tool.ruff]
preview = trueBehavior
| Item | What it does |
|---|---|
| --preview | Enable preview rules and behavior |
| --no-preview | Disable preview (the default) |
| [tool.ruff] preview = true | Enable preview via config |
| preview-only rules | Rules selectable only with preview on |
In CI
Enabling preview means accepting that an upgrade can change which rules fire. If you opt in, pin the exact Ruff version in CI so a minor bump does not silently add or remove preview rules and flip the build red.
Common errors in CI
A rule that will not select ("Unknown rule selector" or simply not firing) is often preview-gated; add --preview. A build that passed yesterday and fails today with new violations, with preview on, is classic preview drift from a Ruff upgrade; pin the version and review the changelog before bumping.