pyproject-toml-validator
Validate pyproject.toml files for Python projects against PEP 517/621 standards.
What it does
Checks your pyproject.toml for common mistakes across three areas:
- [project] — name format (PEP 508), version, license (SPDX), classifiers, dependency specs, authors, dynamic fields
- [build-system] — requires, build-backend validation, known backends
- [tool.*] — ruff, mypy, pytest, black, isort section validation with tool-specific rules
Rules (30+)
| Category | Rules | Examples |
|---|---|---|
| Project metadata (10) | Missing name/version, invalid name format, unknown fields, malformed requires-python, unknown classifiers, empty authors, name in dynamic | name = "My Package!" → invalid PEP 508 name |
| Dependencies (4) | Duplicate deps, unpinned deps, overlapping optional groups | requests and Requests both listed |
| Build system (4) | Missing requires/build-backend, empty requires, unknown fields | No [build-system] table |
| Tool sections (12+) | Ruff select/ignore overlap, mypy type mismatches, black/ruff conflict, isort/ruff conflict, unusual line lengths, invalid target versions | [tool.ruff.lint] select = ["E501"] + ignore = ["E501"] |
Output formats
- text — human-readable with severity icons (❌ ⚠️ ℹ️)
- json — structured with summary counts
- summary — one-line PASS/WARN/FAIL
Exit codes
0— no errors (warnings/info allowed)1— errors found (or--strictwith any issue)2— file not found or parse error
Commands
validate
Full validation of all sections.
python3 scripts/pyproject_validator.py validate pyproject.toml
python3 scripts/pyproject_validator.py validate --format json pyproject.toml
python3 scripts/pyproject_validator.py validate --strict pyproject.toml
project
Validate only the [project] table.
python3 scripts/pyproject_validator.py project pyproject.toml
build
Validate only [build-system].
python3 scripts/pyproject_validator.py build pyproject.toml
tools
Validate only [tool.*] sections (ruff, mypy, pytest, black, isort).
python3 scripts/pyproject_validator.py tools --min-severity warning pyproject.toml
Options
| Option | Values | Default | Description |
|---|---|---|---|
--format | text, json, summary | text | Output format |
--min-severity | error, warning, info | info | Filter by minimum severity |
--strict | flag | off | Exit 1 on any issue |
Requirements
- Python 3.11+ (uses
tomllibfrom stdlib) - Falls back to built-in simple TOML parser on Python 3.10
Examples
# Quick check
python3 scripts/pyproject_validator.py validate pyproject.toml
# CI pipeline
python3 scripts/pyproject_validator.py validate --strict --format summary pyproject.toml
# Check only tool configs
python3 scripts/pyproject_validator.py tools --format json pyproject.toml
# Filter noise
python3 scripts/pyproject_validator.py validate --min-severity warning pyproject.toml