pyproject-doctor

Offline deep validator for pyproject.toml that catches the semantic mistakes other tools miss.

Most validators only check TOML syntax. pyproject-doctor goes further: it validates that your versions are PEP 440 compliant, your requires-python is a valid specifier set, your dependencies are PEP 508 compliant, your version constraints are actually satisfiable, your referenced files exist, your URLs are real URLs, your email addresses look right, and your entry-point references are correctly formatted.

What it checks

Install

pip install pyproject-doctor

Or with classifier validation:

pip install "pyproject-doctor[classifiers]"

Usage

# Validate pyproject.toml in the current directory
pyproject-doctor

# Validate a specific file
pyproject-doctor /path/to/pyproject.toml

# JSON output
pyproject-doctor --format json

# SARIF 2.1.0 output (for GitHub code scanning and other SARIF consumers)
pyproject-doctor --format sarif

Exit code is 1 if any error-level diagnostic is found, 0 otherwise.

The sarif format emits a SARIF 2.1.0 log: each diagnostic becomes one result, the diagnostic code is the ruleId, every result points at the analyzed pyproject.toml, and the SARIF level (error, warning, note) is derived from the diagnostic's level.

Pre-commit

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/amaar-mc/pyproject-doctor
    rev: v0.5.0
    hooks:
      - id: pyproject-doctor

Example output

error project.version: version-invalid: 'not.a.version' is not a valid PEP 440 version
error project.dependencies[0]: constraint-unsatisfiable: Dependency 'requests': constraint '>=3.0,<2.0' is unsatisfiable (lower bound 3.0 exceeds upper bound 2.0)
error project.urls.Homepage: url-invalid: URL 'not-a-url' is not a valid absolute URL (must have scheme and host)

License

MIT. Copyright (c) 2026 Amaar Chughtai.