Skip to content

Static analysis configuration

Static analysis performed by the check code and check fmt commands is (by default) backed entirely by Ruff.

Hatch provides default settings that user configuration can extend.

Note

The fmt command is being deprecated. Use hatch check code for linting and hatch check fmt for formatting instead.

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 check code or check fmt command once with the --sync flag e.g.:

hatch check code --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 environments used by the check code and check fmt commands. See the how-to for a detailed example.

The check code command uses the hatch-check-code environment, and the check fmt command uses the hatch-check-fmt environment. The legacy fmt command continues to use the hatch-static-analysis environment.

Dependencies

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

[tool.hatch.envs.hatch-check-code]
dependencies = ["ruff==X.Y.Z"]

[tool.hatch.envs.hatch-check-fmt]
dependencies = ["ruff==X.Y.Z"]

[envs.hatch-check-code]
dependencies = ["ruff==X.Y.Z"]

[envs.hatch-check-fmt]
dependencies = ["ruff==X.Y.Z"]

Scripts

If you want to change the default commands that are executed, you can override the scripts.

For the hatch-check-code environment:

[tool.hatch.envs.hatch-check-code.scripts]
lint-check = "..."
lint-fix = "..."

[envs.hatch-check-code.scripts]
lint-check = "..."
lint-fix = "..."

For the hatch-check-fmt environment:

[tool.hatch.envs.hatch-check-fmt.scripts]
format-check = "..."
format-fix = "..."

[envs.hatch-check-fmt.scripts]
format-check = "..."
format-fix = "..."

The *-fix scripts run by default while the *-check scripts run when the --fix flag is not passed.

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-check-code]
installer = "pip"

[tool.hatch.envs.hatch-check-fmt]
installer = "pip"

[envs.hatch-check-code]
installer = "pip"

[envs.hatch-check-fmt]
installer = "pip"

Default settings

Non-rule settings

Per-file ignored rules

Selected rules

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

There are 631 selected stable rules and 112 selected preview rules.

Selected rules

Unselected

There are 189 unselected rules.

Unselected rules