Configuration

How Ruff and ty find and apply configuration. The user-facing reference is at https://docs.astral.sh/ruff/configuration/ and https://docs.astral.sh/ruff/settings/; this page covers the shape and the source of truth.

Files Ruff reads

In each directory walked from the file being checked up to the project root, Ruff looks for:

1. pyproject.toml with a [tool.ruff] section.
2. ruff.toml.
3. .ruff.toml.

The first match wins for that directory. extend = "../base.toml" chains files. CLI flags override file settings.

The full discovery algorithm is in crates/ruff_workspace/src/resolver.rs.

Files ty reads

• pyproject.toml with a [tool.ty] section.
• ty.toml at the project root.

Project loading is in crates/ty_project/.

Schemas

The repo ships generated JSON Schemas at the root:

• ruff.schema.json
• ty.schema.json

Regenerate with cargo dev generate-all (or RUFF_UPDATE_SCHEMA=1 cargo test). Editors with Schema Store integration will pick these up automatically.

Top-level Ruff options (selected)

Option	Default	Notes
line-length	88	Used by linter and formatter.
indent-width	4	Used by formatter.
target-version	py310	Affects rule behavior and parser features.
exclude	(project ignore set)	Glob patterns to skip.
extend-exclude	empty	Add to exclude without overriding defaults.
respect-gitignore	true	Honor .gitignore during file discovery.
cache-dir	.ruff_cache	Per-project cache location.
preview	false	Enable preview rules and behaviors.
output-format	text	Default output format.

[lint] options

Option	Notes
select, extend-select	Rule selectors to enable.
ignore, extend-ignore	Rule selectors to disable.
fixable, unfixable, extend-fixable	Control which rules' fixes are applied.
per-file-ignores, extend-per-file-ignores	Glob → rule list.
dummy-variable-rgx	Regex for "intentional unused variables".
task-tags	Tags recognized by FIX/TODO rules.
typing-modules	Modules treated as typing for analysis.
pydocstyle.convention, flake8-bugbear.extend-immutable-calls, etc.	Per-plugin sub-settings.

[format] options

Option	Notes
quote-style	single, double, preserve.
indent-style	space, tab.
skip-magic-trailing-comma	Mirrors Black.
line-ending	auto, lf, crlf, cr, native.
docstring-code-format, docstring-code-line-length	Format code in docstrings.
preview	Format-side preview mode.
exclude, extend-exclude	Format-only excludes.

ty options (selected)

Option	Notes
python-version	Target Python version (3.10, 3.11, 3.12, 3.13, 3.14).
python	Path to a Python interpreter; used to discover site-packages.
include, exclude	File globs.
lint.<rule>	Per-rule severity overrides.

crates/ty_project/src/configuration.rs is the source of truth.

Source of truth — Ruff

• The Options struct in crates/ruff_workspace/src/options.rs.
• Each lint plugin contributes its own Options sub-struct inside crates/ruff_linter/src/rules/<plugin>/.
• Macros in ruff_macros and ruff_options_metadata extract the doc strings, types, and defaults at build time.

Source of truth — ty

• crates/ty_project/src/configuration.rs for project-wide options.
• crates/ty_python_semantic/src/lint.rs for per-lint metadata.

Adding an option

1. Add the field to the relevant Options struct (with a docstring).
2. Plumb it through to Settings.
3. Run cargo dev generate-all or RUFF_UPDATE_SCHEMA=1 cargo test.
4. Add a test that exercises the new behavior.
5. Mention the option in the user docs (docs/).

See crates/ruff_workspace for the Ruff-side details and features/type-checker for ty configuration in context.