Scan any Python codebase and get a 0–100 health score. 9 analyzers. Project profiles. Built for AI agents.
pip install python-doctor · uv tool install python-doctor · pipx install python-doctor
Wraps Bandit, Ruff, Vulture, Radon, and 4 custom AST analyzers into a single score.
Auto-detects your project type. Configurable via [tool.python-doctor] in pyproject.toml.
Auto-detects your project type from pyproject.toml and adjusts scoring. Override with --profile or config.
Run, read, fix, verify. Python Doctor was designed for this loop from day one.
Run python-doctor . --json and get structured findings with file paths and line numbers.
Use --fix for auto-fixable issues. The agent handles the rest by reading the JSON output.
Re-run with --score to confirm the score improved. Exit code 1 if below 50.
Score target met. Run --badge for a README badge. Use --ci to auto-update it on every push.
If it can run a shell command, it can use Python Doctor.
/python-doctor slash command after modifying Python files..cursor/rules/ and it runs automatically on Python changes.AGENTS.md. Codex reads it and runs the scan automatically.--ci to generate the workflow.Strict, opinionated scores. These are real scans on real repos.
| Project | Stars | Score | Top findings |
|---|---|---|---|
| requests | 52k+ | 42/100 | Weak hashes (B324), complexity (CC 21), large files, no type hints |
| flask | 69k+ | 47/100 | Hardcoded passwords, complexity (CC 23), large files (app.py: 1625 lines), bare except |
| fastapi | 82k+ | 26/100 | B101 asserts in source, routing.py (4956 lines), 6% docstring coverage |
| python-doctor | — | 98/100 | Dogfooded. Ran on itself, fixed everything it found. |
One command. Thirty seconds. No config.