Configuration

pyproject.toml

Configure pycmdcheck in your project’s pyproject.toml file under the [tool.pycmdcheck] section:

[tool.pycmdcheck]
skip = ["ST001", "MT003"]
skip_groups = ["metadata"]
only = ["ST002", "ST003"]
only_groups = ["structure"]
error_on = "warning"

Options

`skip`

List of check IDs to skip:

[tool.pycmdcheck]
skip = ["ST001", "MT003"]

`skip_groups`

List of check groups to skip entirely:

[tool.pycmdcheck]
skip_groups = ["metadata", "tests"]

`only`

Only run these specific check IDs (skip all others):

[tool.pycmdcheck]
only = ["ST001", "ST002", "ST003"]

`only_groups`

Only run checks in these groups:

[tool.pycmdcheck]
only_groups = ["structure"]

`error_on`

Minimum severity level that causes a non-zero exit code:

[tool.pycmdcheck]
error_on = "warning"  # Options: "error", "warning", "note"

Default is "error", meaning only ERROR severity checks cause exit code 1.

Check-Specific Configuration

Configure individual checks using [tool.pycmdcheck.checks.<CHECK_ID>]:

[tool.pycmdcheck.checks.TS002]
parallel = true       # Run tests in parallel
workers = "auto"      # Number of workers ("auto" or integer)
timeout = 300         # Timeout in seconds (optional)

[tool.pycmdcheck.checks.TS003]
coverage_threshold = 70  # Minimum coverage percentage
parallel = true
workers = 4

[tool.pycmdcheck.checks.DP004]
ignore_modules = ["mypackage.legacy"]
max_cycles = 5

Each check may support different configuration options. Use pycmdcheck explain <CHECK_ID> to see available options.

CLI Options

CLI options override pyproject.toml configuration:

# Skip checks (overrides pyproject.toml skip)
pycmdcheck --skip ST001 --skip MT003

# Skip groups
pycmdcheck --skip-group metadata

# Only run specific checks
pycmdcheck --only ST001 --only ST002

# Only run specific groups
pycmdcheck --only-group structure

# Set error threshold
pycmdcheck --error-on warning

Python API Options

Options passed to check() or check_async() override pyproject.toml:

import pycmdcheck

results = pycmdcheck.check(
    "./my-package",
    skip_ids=["ST001", "MT003"],
    skip_groups=["tests"],
    only_ids=None,  # None means "use pyproject.toml or run all"
    only_groups=None,
    error_on="warning"
)

Configuration Precedence

Configuration is loaded in this order (later overrides earlier):

Default values - Built into pycmdcheck
pyproject.toml - [tool.pycmdcheck] section
CLI options or API options - Highest priority

Example

Given this pyproject.toml:

[tool.pycmdcheck]
skip = ["ST001"]
error_on = "warning"

And this CLI command:

pycmdcheck --skip ST002

The effective configuration is:

skip = ["ST002"] (CLI overrides pyproject.toml)
error_on = "warning" (from pyproject.toml, not overridden)

Check Groups

Available check groups:

Group	Checks	Description
`structure`	ST001-ST008	Package structure (README, LICENSE, src layout)
`metadata`	MT001-MT010	pyproject.toml metadata (name, version, classifiers)
`tests`	TS001-TS004	Test directory, execution, coverage, naming
`documentation`	DC001-DC005	Docstrings, docs directory, API docs
`code-quality`	CQ001-CQ008	Linting, type hints, complexity, doctests
`dependencies`	DP001-DP005	Version pinning, lockfiles, circular imports
`security`	SC001-SC005	Credentials, insecure functions, vulnerabilities
`build`	BD001-BD004	Build, wheel, install, import verification
`release`	RL001-RL003	Changelog, semantic versioning, git tags

Example Configurations

Minimal (strict)

Use all defaults - fail on any ERROR:

# No [tool.pycmdcheck] section needed

Development (lenient)

Allow warnings during development:

[tool.pycmdcheck]
error_on = "note"  # Only fail on notes (effectively never)

CI (strict with skips)

Skip certain checks in CI:

[tool.pycmdcheck]
skip = ["MT003"]  # Skip description check
error_on = "warning"  # Fail on warnings too

Focus on structure only

When you only care about basic structure:

[tool.pycmdcheck]
only_groups = ["structure"]