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

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.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.2.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.2.0
File Size Uploaded Provenance Actions
pydoctor_cli-2.2.0.tar.gz 90.7 kB With provenance Details for pydoctor_cli-2.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 193.4 kB

Release files / pydoctor_cli-2.2.0.tar.gz

Download URL pydoctor_cli-2.2.0.tar.gz
Size 90.7 kB
Tags Source
SHA-256 checksum
How to use checksums
faf5e566ce0ece06340c6fbccc0358d96a3a227399c128b4f6ce8a9c67f77a9f
BLAKE2b-256 checksum
How to use checksums
dcbef191c715dae8b0b7586ed77db7fb0fd71f2017299bb3357c346ce3bc72d1
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 28, 2026.

Transparency log

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

Download URL pydoctor_cli-2.2.0-py3-none-any.whl
Size 102.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58a7071a849bf28a611d8992e0bfbc5615fb2b4eb6ccf0f162d20b66c86c478c
BLAKE2b-256 checksum
How to use checksums
2413cdab16efd05a793960373d72bb12b91a611507c20d6a4b24433045b80655
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 28, 2026.

Transparency log

Security for pydoctor-cli 2.2.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.2.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 28, 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