---
title: Quickstart
description: Install pydoctor-cli, run your first diagnostic scan, and read the results.
url: https://pydoctor-docs.thally.app/quickstart
---

# Quickstart

Install pydoctor-cli, run your first diagnostic scan, and read the results.

Run a full diagnostic scan on a Python project and understand the output.

## Before you begin

- Python 3.10 or later
- Network access to `api.osv.dev` (for the vulnerability scan) and `pypi.org` (for the outdated-packages check)
- A Python project with a virtual environment (recommended) and installed dependencies

#### Install pydoctor-cli

    ```bash
    pip install pydoctor-cli
    ```

> **Install pydoctor-cli, not pydoctor:**
      The PyPI package `pydoctor` is a different project: Twisted's API documentation generator. Both packages install into the same `pydoctor` import directory and both provide a `pydoctor` command, so installing both in one environment breaks whichever was installed first. If you see unexpected output, see [Troubleshooting](/guides/troubleshooting#wrong-pydoctor).

    Verify the installation:

    ```bash
    pydoctor --version
    ```

    You should see `PyDoctor version 2.0.1` or later.

#### Run a diagnostic scan

    Navigate to your project directory and run:

    ```bash
    pydoctor diagnose
    ```

    This runs every built-in scanner (environment, dependencies, outdated packages, security vulnerabilities, unused packages, and CI hygiene) and prints a report to your terminal.

    If no virtual environment is detected, pydoctor prompts you to confirm before continuing with system-wide packages. You can activate a virtual environment and retry, or confirm to proceed.

#### Read the results

    The report groups issues by category and assigns each one a severity:

    | Severity | Meaning |
    |---|---|
    | `ok` | Check passed, no action needed |
    | `info` | Informational, such as a minor version update available |
    | `warning` | Worth investigating but not blocking |
    | `error` | A concrete problem, such as a dependency conflict or a medium-severity vulnerability |
    | `critical` | Requires immediate attention, such as a high-severity vulnerability or an exposed secret |

    At the bottom of the report, a health score from 0 to 100 summarizes the overall state of the project. The verdict label is Excellent (90+), Good (70+), Needs Attention (50+), or Critical (below 50).

#### Check the exit code

    `pydoctor diagnose` exits with code 1 when:

    - any issue has `error` or `critical` severity, or
    - the project’s `min_health_score` threshold (set in `[tool.pydoctor]` in `pyproject.toml`) is above 0 and the calculated score falls below it.

    Otherwise the exit code is 0. This makes it safe to use as a gate in scripts or CI pipelines.

## Get JSON output

Add `--json` to any scan command (`diagnose`, `check`, `scan-security`, `scan-unused`, `scan-deps`, `check-env`, `github`) to get machine-readable output instead of the Rich terminal display:

```bash
pydoctor diagnose --json
```

In JSON mode the virtual-environment prompt is skipped and the scan runs non-interactively.

## Next steps

- See the full list of commands and flags in [Commands](/cli/commands).
- Set up pydoctor as a CI gate in [CI integration](/guides/ci-integration).
- Let pydoctor fix issues automatically with [Fixing issues](/guides/fixing-issues).
- Something not working? See [Troubleshooting](/guides/troubleshooting).