---
title: Introduction
description: pydoctor-cli scans Python projects for security vulnerabilities, dependency problems, unused packages, environment issues, and CI/CD risks, then scores overall project health.
url: https://pydoctor-docs.thally.app/
---

# Introduction

pydoctor-cli scans Python projects for security vulnerabilities, dependency problems, unused packages, environment issues, and CI/CD risks, then scores overall project health.

pydoctor-cli is a command-line tool that scans Python projects for common dependency and security problems. It requires Python 3.10 or later and works with pip, Poetry, uv, and pdm. See the [changelog](/changelog) for the latest release.

## What it scans

pydoctor-cli runs six scanners, each focused on a different risk area:

#### [Security](/scanners)

    Queries the OSV vulnerability database for known issues in your installed packages.

#### [Dependencies](/scanners)

    Runs `pip check` to find version conflicts and missing dependencies.

#### [Outdated packages](/scanners)

    Lists installed packages with newer releases available, flagging major version gaps as warnings.

#### [Unused packages](/scanners)

    Finds declared dependencies that nothing in your code, settings, or run files appears to use.

#### [Environment health](/scanners)

    Checks your Python version, virtual environment, and pip version against recommended baselines.

#### [CI/CD checks](/scanners)

    Scans Python files for leaked secrets and workflow files for unpinned actions or cleartext credentials.

## Health score

Every scan produces a health score on a 0 to 100 scale. The score starts at 100 and decreases based on the severity and category of each issue found. Four verdict bands summarize the result:

| Score | Verdict |
|---|---|
| 90 to 100 | Excellent |
| 70 to 89 | Good |
| 50 to 69 | Needs Attention |
| 0 to 49 | Critical |

You can set a minimum passing score in your `pyproject.toml` with the `min_health_score` option under `[tool.pydoctor]`. When the score falls below that threshold, the CLI exits with code 1, which makes it straightforward to use as a CI gate.

## Output formats

By default, results render as Rich terminal panels grouped by category, with a colored health-score bar and a next-steps guide. Pass `--json` to any scan command for machine-readable JSON output suitable for CI pipelines or further processing.

## Get started

#### [Quickstart](/quickstart)

    Install pydoctor-cli and run your first scan in a few minutes.

#### [CLI commands](/cli/commands)

    Full reference for every command, flag, and option.

#### [Configuration](/configuration)

    Tune ignored packages, health thresholds, cache TTL, and worker counts.

#### [CI integration](/guides/ci-integration)

    Add pydoctor-cli to GitHub Actions or GitLab CI as a quality gate.