Settings¶

All settings live in konform.toml (under [konform]) or pyproject.toml (under [tool.konform]). Tables below use the pyproject.toml form. See Configuration for file discovery.

Top-level: [tool.konform]¶

extend¶

Path of a config file to inherit from, relative to this one (~/ is expanded). This file's settings are laid over it; see Sharing configuration.

Default: none · Type: str

[tool.konform]
extend = "../shared/konform.toml"

cache-dir¶

Directory for the result cache.

Default: ".konform_cache" · Type: str

workers¶

Number of worker threads. 0 means os.cpu_count().

Default: 0 · Type: int

python¶

Python interpreter used to resolve imports. If unset, .venv, venv and .env are auto-discovered.

Default: auto-discovered · Type: str

src¶

Extra module search roots for KIS001, relative to the config file. Falls back to [tool.ruff] src, then [".", "src"].

Default: [".", "src"] · Type: list[str]

[tool.konform]
src = ["lib"]

exclude¶

Glob patterns of files to skip. A file is skipped when its path relative to the config file, or any of its parent directories inside the project, matches as a path or by name, so gen/**, *_pb2.py and a bare directory name such as build all work. Applies to explicitly named files too, so it also works from pre-commit.

Default: [] · Type: list[str] · CLI: --exclude (replaces the list)

[tool.konform]
exclude = ["build", "gen/**", "*_pb2.py"]

extend-exclude¶

Patterns to skip in addition to exclude. Use it to add to an exclude that --exclude would otherwise replace.

Default: [] · Type: list[str] · CLI: --extend-exclude

Linter: [tool.konform.lint]¶

select¶

Rule codes or prefixes to enable. Empty means all default rules.

Default: [] · Type: list[str] · CLI: --select

extend-select¶

Rule codes or prefixes to enable on top of select. Required for opt-in rules such as KNQ001.

Default: [] · Type: list[str] · CLI: --extend-select

ignore¶

Rule codes or prefixes to disable (prefix-matched).

Default: [] · Type: list[str] · CLI: --ignore, --extend-ignore

fixable¶

Rule codes or prefixes whose violations may be auto-fixed. Empty means every code. See Fixes.

Default: [] · Type: list[str]

unfixable¶

Rule codes or prefixes that are never auto-fixed, even if fixable matches. Their violations are still reported.

Default: [] · Type: list[str]

level¶

Minimum severity that causes a non-zero exit.

Default: "error" · Type: "warning" | "error" · CLI: --level

per-file-ignores¶

Map of glob (relative to the project root) to codes to ignore for matching files.

Default: {} · Type: dict[str, list[str]] · CLI: --per-file-ignores, --extend-per-file-ignores

[tool.konform.lint.per-file-ignores]
"tests/**" = ["KIS001", "KPT"]

noqa-aliases¶

Map of alternate code to canonical code so old # noqa comments keep working. See Suppressing violations.

Default: {} · Type: dict[str, str]

Rule tables¶

Keyed by config name under [tool.konform.lint].

module-only-imports (KIS001)¶

import-alias-policy (KIS002)¶

user-defined-patterns (KPT)¶

structural-rules (KST)¶

Full example¶

[tool.konform]
cache-dir = ".konform_cache"
workers   = 0
src       = [".", "src"]
exclude   = []

[tool.konform.lint]
select    = []
ignore    = []
fixable   = []
unfixable = []
level     = "error"

[tool.konform.lint.module-only-imports]
exceptions = ["__future__", "typing", "typing_extensions", "collections.abc", "mycompany.compat"]
level = "error"
unresolved-level = "warning"

[tool.konform.lint.import-alias-policy]
level = "warning"
# alias-template = "{module_last}_{name}"

[tool.konform.lint.user-defined-patterns]
level = "warning"
# rules_file = "konform_patterns.toml"

[[tool.konform.lint.user-defined-patterns.rules]]
id      = "KPT001"
message = "Use the project logger instead of bare print()."
pattern = '^\s*print\s*\('
files   = ["src/**/*.py"]
level   = "warning"