Ruff Config in pyproject.toml
Ruff configures itself from the [tool.ruff] table in pyproject.toml, with linting under [tool.ruff.lint] and formatting under [tool.ruff.format].
pyproject.toml is the canonical home for Ruff config. Knowing the section layout avoids silently ignored settings.
What it does
Ruff auto-discovers pyproject.toml and reads [tool.ruff] for top-level options like line-length and target-version, [tool.ruff.lint] for rule selection and per-file-ignores, and [tool.ruff.format] for formatter options. Settings here apply to every ruff check and ruff format in the project.
Common usage
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]
ignore = ["E501"]
[tool.ruff.format]
quote-style = "double"Config keys
| Key | What it does |
|---|---|
| [tool.ruff] line-length | Max line length (default 88) |
| [tool.ruff] target-version | Lowest Python version to support |
| [tool.ruff.lint] select / ignore | Rule selection |
| [tool.ruff.lint] per-file-ignores | Path-scoped ignores |
| [tool.ruff.format] quote-style | Formatter quote preference |
| extend | Inherit from another config file |
In CI
Commit pyproject.toml so the runner and developers share one config. Run ruff check --show-settings locally to confirm the resolved configuration if a setting seems ignored.
Common errors in CI
Lint settings placed directly under [tool.ruff] (e.g. select) rather than [tool.ruff.lint] are deprecated and may warn or be ignored, so a rule set looks active locally but not in CI. "Failed to parse" with a TOML error and exit 2 means a syntax mistake in pyproject.toml. A nearby ruff.toml overrides pyproject.toml, which can explain config that seems not to apply.