Skip to content

Static analysis configuration

Static analysis performed by the fmt command is (by default) backed entirely by Ruff.

Hatch provides default settings that user configuration can extend.

Extending config

When defining your configuration, be sure to use options that are prefixed by extend- such as extend-select, for example:

[tool.ruff.format]
preview = true
quote-style = "single"

[tool.ruff.lint]
preview = true
extend-select = ["C901"]

[tool.ruff.lint.extend-per-file-ignores]
"docs/.hooks/*" = ["INP001", "T201"]

[tool.ruff.lint.isort]
known-first-party = ["foo", "bar"]

[format]
preview = true
quote-style = "single"

[lint]
preview = true
extend-select = ["C901"]

[lint.extend-per-file-ignores]
"docs/.hooks/*" = ["INP001", "T201"]

[lint.isort]
known-first-party = ["foo", "bar"]

Note

When not persisting config, there is no need to explicitly extend the defaults as Hatch automatically handles that.

Persistent config

If you want to store the default configuration in the project, set an explicit path like so:

[tool.hatch.envs.hatch-static-analysis]
config-path = "ruff_defaults.toml"

[envs.hatch-static-analysis]
config-path = "ruff_defaults.toml"

Then instruct Ruff to consider your configuration as an extension of the default file:

[tool.ruff]
extend = "ruff_defaults.toml"

extend = "ruff_defaults.toml"

Anytime you wish to update the defaults (such as when upgrading Hatch), you must run the fmt command once with the --sync flag e.g.:

hatch fmt --check --sync

Tip

This is the recommended approach since it allows other tools like IDEs to use the default configuration.

No config

If you don't want Hatch to use any of its default configuration and rely entirely on yours, set the path to anything and then simply don't extend in your Ruff config:

[tool.hatch.envs.hatch-static-analysis]
config-path = "none"

[envs.hatch-static-analysis]
config-path = "none"

Customize behavior

You can fully alter the behavior of the environment used by the fmt command. See the how-to for a detailed example.

Dependencies

Pin the particular version of Ruff by explicitly defining the environment dependencies:

[tool.hatch.envs.hatch-static-analysis]
dependencies = ["ruff==X.Y.Z"]

[envs.hatch-static-analysis]
dependencies = ["ruff==X.Y.Z"]

Scripts

If you want to change the default commands that are executed, you can override the scripts. The following four scripts must be defined:

[tool.hatch.envs.hatch-static-analysis.scripts]
format-check = "..."
format-fix = "..."
lint-check = "..."
lint-fix = "..."

[envs.hatch-static-analysis.scripts]
format-check = "..."
format-fix = "..."
lint-check = "..."
lint-fix = "..."

The format-* scripts correspond to the --formatter/-f flag while the lint-* scripts correspond to the --linter/-l flag. The *-fix scripts run by default while the *-check scripts correspond to the --check flag.

Reminder

If you choose to use different tools for static analysis, be sure to update the required dependencies.

Installer

By default, UV is enabled. You may disable that behavior as follows:

[tool.hatch.envs.hatch-static-analysis]
installer = "pip"

[envs.hatch-static-analysis]
installer = "pip"

Default settings

Non-rule settings

Per-file ignored rules

Selected rules

The following rules are based on version 0.4.2 of Ruff. Rules with a P are only selected when preview mode is enabled.