Skip to main content

PyDoctor CLI (Command Line Interface)

PyDoctor is a standalone, developer-friendly diagnostic assistant for Python environments. It acts like a personal physician for your code — scanning your project and environment to prescribe fixes for misconfigurations, dependencies, and security vulnerabilities.

PyPI Downloads CI Status PyPI version Python versions License


🧭 Navigation


Project Description

PyDoctor isn't just a scanner; it's a complete remediation tool that performs static analysis on your project files and cross-references your environment against live security databases.

Key Features

  • Environment Analysis: Detects missing virtualenvs, outdated pip, or deprecated Python versions.
  • Dependency Fix: Automatically resolves conflicts and installs missing packages.
  • Security: Integrates with OSV.dev API to check against known CVEs/GHSAs.
  • Unused Detection: Identifies declared packages that are never imported.
  • Multi-Manager: Intelligent support for pip, Poetry, uv, and pdm.
  • Rich UI: Beautiful progress spinners, icons, and color-coded severities.

📦 Installation

PyDoctor requires Python 3.10+. For the best experience, we recommend using pipx.

# Recommended: Install globally in an isolated environment
pipx install pydoctor-cli

# Standard pip installation
pip install pydoctor-cli

Install pydoctor-cli, not pydoctor: that is an unrelated project (Twisted's API doc generator) that installs a command with the same name.

PyDoctor scans your project's Python, wherever PyDoctor itself is installed. It uses the active virtualenv, or a .venv/venv in the project, and tells you which interpreter it chose. To choose one yourself:

pydoctor diagnose --python .venv/bin/python   # or set PYDOCTOR_PYTHON

📖 Full documentation: https://pydoctor-docs.thally.app


⚡ Usage

Full Diagnosis

Run a comprehensive check-up on your project.

pydoctor diagnose

In CI: GitHub Action

Findings appear as code-scanning alerts on pull requests, and the job fails on new problems:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with: { python-version: "3.12" }
  - run: pip install -r requirements.txt
  - uses: iamAgbaCoder/pydoctor-cli@v2

Set ci-only: "true" to run only the secrets and workflow checks. Any CI system can use pydoctor check --sarif pydoctor.sarif directly.

Adopting it in an existing project: baselines

pydoctor baseline        # accept today's issues; commit .pydoctor-baseline.json
pydoctor check           # now fails only on new issues

Problems with the scan itself (unreadable environment, unreachable vulnerability database) are never baselined.

pre-commit

repos:
  - repo: https://github.com/iamAgbaCoder/pydoctor-cli
    rev: v2.3.0
    hooks:
      - id: pydoctor-ci      # blocks commits that add secrets or risky workflows

Automated Fixes

Let PyDoctor perform the heavy lifting. It will offer to install missing packages, upgrade outdated ones, and clean up your environment.

pydoctor fix

Release History

v2.3.0

Built for CI: adopt pydoctor in an existing project without a wall of failures, and see findings where you review code.

  • Baselines: pydoctor baseline records today's issues in .pydoctor-baseline.json; scans then fail only on new ones and tell you when baselined issues are fixed. Fingerprints survive unrelated edits (a secret moved down by new lines stays known) and package upgrades. --ci updates only the CI-guard entries. --baseline FILE / --no-baseline on every scan command. Broken scans are never baselined.
  • SARIF output: --sarif FILE on every scan command (SARIF 2.1.0, schema-validated). Vulnerabilities carry their CVSS score as security severity and point at the line that declares the package; secrets and workflow findings point at their file and line.
  • GitHub Action: uses: iamAgbaCoder/pydoctor-cli@v2 installs pydoctor in isolation, uploads findings to code scanning, and fails the job on new problems.
  • pre-commit hooks: pydoctor-ci blocks commits that add secrets, .env files or risky workflows; pydoctor-check runs the full scan at pre-push.
  • Docs links: every issue links to its page on pydoctor-docs.thally.app (docs_url in JSON; shown in the terminal for errors).

v2.2.0

Results you can trust: every fix in this release removes a case where PyDoctor reported a problem as fine, or got a severity wrong.

  • Scans the right environment: facts come from your project's interpreter, not PyDoctor's. Under pipx or uv tool, and in uv environments (which have no pip), 2.1.0 saw 0 packages and reported everything as OK. Works without pip (package metadata, uv pip list --outdated). New --python / PYDOCTOR_PYTHON; the report shows which interpreter was scanned and why.
  • Fails loudly: ENV_PACKAGES_UNAVAILABLE (error) when the environment can't be read, ENV_DEPS_NOT_INSTALLED when the scanned Python has none of your dependencies, and outdated checks that can't run say so instead of "all up to date".
  • Virtualenv detection works: it was always "active". The diagnose no-venv prompt now appears, and never blocks CI or piped runs.
  • Real CVSS scores: severity is computed from the CVSS v3 vector. Previously a 3.1 (Low) and a 9.8 (Critical) vulnerability were both shown as critical. GitHub's MODERATE is now medium.
  • Right fix version: for advisories with one fix per release line, fix targets your line (Django 5.1.2 → 5.1.4, not 4.2.17).
  • CI guard finds real leaks: scans every committed text file, adds Stripe, OpenAI, Anthropic, Slack, Google, private-key, database-URL and SECRET_KEY rules, flags committed .env files, and checks workflows for pull_request_target "pwn requests", script injection and write-all permissions. Findings have line numbers; add # pydoctor: ignore to silence one. Zero findings on Flask, Django, requests, httpx, FastAPI, DRF and pip.
  • A score that moves: a package's advisories count once, categories have diminishing returns, and any critical issue keeps the score below "Good". Expect different (usually higher) scores than 2.1.0.
  • JSON: includes health; scan-security --json reports advisory IDs, aliases, fixed version and CVSS score.
  • Smaller: database drivers, hashers and cache clients picked by Django settings count as used; faster advisory fetching; --no-cache no longer wipes the cache; circular import fixed; github <repo> and docker describe what they actually do.

v2.1.0

  • pydoctor fix reports what really happened: upgrades are verified against the installed version. If a pin in pyproject.toml blocks an upgrade, pydoctor says so and shows the constraint instead of printing "fixed".
  • One prompt per package: vulnerable packages are offered once, with the advisory count, and upgraded to the lowest version that fixes every advisory.
  • No accidental removals: pydoctor fix <package> no longer offers to uninstall it. Removal only runs with --remove.
  • Fewer false "unused" reports: packages imported under a different name (decouple), loaded from strings (Django INSTALLED_APPS, MIDDLEWARE, backends), or run from a Procfile/Dockerfile (gunicorn) are recognised as used. Remaining findings are labelled "Possibly unused".

v2.0.1

  • Security scans fail closed: if the OSV database can't be reached, pydoctor now reports SEC_SCAN_INCOMPLETE (error, exit 1) instead of a clean result.
  • No more double-counted advisories: advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.

v2.0.0

  • 🚀 Major UI/UX Revamp: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.
  • 🛡️ CI/CD Guard Mode: New pydoctor check --ci command to detect exposed secrets (AWS, GitHub, PyPI tokens) and insecure workflow patterns in GitHub Actions/GitLab CI.
  • 🐳 Docker Support: New pydoctor docker command to diagnose Python issues inside containers and audit Dockerfiles.
  • 🐙 GitHub Integration: New pydoctor github command for repository-wide health scans and local git configuration audits.
  • 📈 Advanced Health Scoring: Refined the 0-100 scoring algorithm with granular penalties for security vulnerabilities and CI/CD risks.
  • ⚡ Performance Boost: Parallel execution engine for scanning large codebases faster.
  • 🔍 Smart Environment Detection: Now automatically prompts users when no venv is found, preventing accidental system-wide changes.
  • 🎯 Context-Aware Reporting: Targeted commands (like pydoctor scan-unused or pydoctor github) now intelligently suppress unrelated scanner noise.
  • 🧠 OSV Deep-Fetching: Overcame upstream OSV API batch limits by implementing dynamic real-time fetching and caching of full vulnerability advisories natively.
  • 🔗 Transitive Dependency Tracking: PyDoctor now uniquely segregates mathematical/transitive dependencies from pure unused bloat, effectively preventing pydoctor fix from uninstalling required sub-packages.
  • 🛠️ Refined Git Discovery: Utilizes native git heuristics (--is-inside-work-tree & --show-toplevel) to flawlessly map out project roots and repository states, even when scanning from deeply nested sub-directories.
  • 🔮 Dynamic Fix Suggestions: The 🚀 Next Steps terminal guide now dynamically rules out the currently running command and gracefully self-hides when a project achieves a perfect 100/100 health rating.

v0.1.3

  • Enhanced Package Detection: Pydoctor now intelligently detects and uses your project's specific virtual environment (Poetry, UV, PDM, or standard venv) to run all scans and diagnoses.
  • Improved Architecture: Refactored core modules to reduce complexity and improve maintainability (resolved C901 linting errors).
  • Fix Rendering Errors: Resolved issues with undefined verbose detail renderers in the CLI.

v0.1.2

  • Maintenance: Minor internal fixes and linting improvements for CI/CD stability.
  • Professional Meta: Revamped pyproject.toml with complete author metadata and SEO keywords.

v0.1.1

  • Bug Fixes: Minor improvements to dependency scanning reliability.
  • Metadata Update: Initial professional README branding.

v0.1.0

  • Initial Release: Core diagnostic engine with support for Environment, Dependencies, Outdated Packages, Security, and Unused Package scans.
  • Remediation: Initial support for auto-fixing issues via pydoctor fix.

Verified Details


👥 Maintainers

📄 Meta

  • License: Apache License 2.0
  • Author: Favour Bamgboye
  • Requires: Python >=3.10
  • Classifiers:
    • Development Status :: 4 - Beta
    • Intended Audience :: Developers
    • License :: OSI Approved :: Apache Software License
    • Operating System :: OS Independent
    • Programming Language :: Python :: 3
    • Programming Language :: Python :: 3.10
    • Programming Language :: Python :: 3.11
    • Programming Language :: Python :: 3.12
    • Topic :: Software Development :: Quality Assurance

Developed with ❤️ by Favour Bamgboye

Metadata

Release files for pydoctor-cli 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pydoctor-cli 2.3.0
File Size Uploaded Provenance Actions
pydoctor_cli-2.3.0.tar.gz 102.6 kB With provenance Details for pydoctor_cli-2.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pydoctor-cli 2.3.0
File Interpreter ABI Platform Actions
pydoctor_cli-2.3.0-py3-none-any.whl Python 3 none any Details for pydoctor_cli-2.3.0-py3-none-any.whl

Total release size: 219.9 kB

Release files / pydoctor_cli-2.3.0.tar.gz

Download URL pydoctor_cli-2.3.0.tar.gz
Size 102.6 kB
Tags Source
SHA-256 checksum
How to use checksums
032db9044703d9053b1e77eb2001eab707a673c87bd5f62d065c9720e6df7d70
BLAKE2b-256 checksum
How to use checksums
d579a7ac1419e24883217a69ed2c1a5fddff15900578e28c5d3c6809bc69733d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / pydoctor_cli-2.3.0-py3-none-any.whl

Download URL pydoctor_cli-2.3.0-py3-none-any.whl
Size 117.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8b03ed9bbb2aa89856ec20c968e5a29d958c4e483dba75d866d636bf1bb1ec6
BLAKE2b-256 checksum
How to use checksums
d6bafd6893196c3fab26fafe07ca90d033785269bbeb121d310d0e5d840c98c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for pydoctor-cli 2.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pydoctor_cli-2.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page