pubspec_doctor 0.2.0

CLI that audits pubspec.yaml dependencies: finds unused packages and flags discontinued or stale ones using the pub.dev API.

pubspec_doctor

CLI that audits the dependencies in your pubspec.yaml:

• Unused — declared in dependencies / dev_dependencies but never referenced in the project.
• Discontinued — flagged as discontinued on pub.dev, including the suggested replacement package when the author provided one.
• Stale — the latest release is older than a threshold (2 years by default), a common sign of an unmaintained package.

Existing tools cover these separately (dependency_validator for unused, dart pub outdated shows discontinued); pubspec_doctor gives you a single report and a single CI gate.

Install

dart pub global activate pubspec_doctor

Usage

Run it from your project root (or point it anywhere with --path):

pubspec_doctor

Example output:

pubspec_doctor — diagnosis for "my_app" (14 dependencies checked)

Unused dependencies:
  - collection
  - rxdart

Discontinued packages:
  - flutter_markdown (replaced by: flutter_markdown_plus)

Stale packages (no release in a long time):
  - some_pkg (latest 0.3.1 published 1204 days ago)

Options

Flag	Description
-p, --path	Project root containing pubspec.yaml (default: .).
-i, --ignore	Package names to exclude from all checks (repeatable).
--stale-days	Staleness threshold in days (default: 730).
--offline	Skip pub.dev health checks; unused analysis only.
--fail-on-stale	Non-zero exit code when stale packages are found.
--json	Machine-readable JSON report.

Exit codes

Code	Meaning
0	No problems found.
1	Unused or discontinued packages found (stale too, with --fail-on-stale).
2	Usage or runtime error (e.g. no pubspec.yaml).

CI integration

The exit code makes pubspec_doctor behave like a test suite: 0 passes the build, 1 fails it. On GitHub Actions, findings are also emitted as annotations, so unused or discontinued packages show up directly on pubspec.yaml in the pull request UI.

The easiest way is the bundled GitHub Action:

name: Dependency audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: PopovVA/pubspec_doctor@main
        with:
          # path: packages/my_app        # for monorepos
          args: --fail-on-stale --ignore build_runner

Or run the CLI yourself on any CI system:

- run: dart pub global activate --source git https://github.com/PopovVA/pubspec_doctor.git
- run: dart pub global run pubspec_doctor --fail-on-stale

For machine-readable pipelines, combine --json with jq:

pubspec_doctor --json | jq '.unusedDependencies'

How "unused" is detected

A package counts as used when it appears as a package:<name>/ URI in any Dart file (imports, exports and conditional imports), in an analysis_options.yaml include (so lints / flutter_lints are not false positives), or as a packages/<name>/ asset or font reference in pubspec.yaml. SDK dependencies (flutter, flutter_test, …) are skipped.

Packages that are genuinely used without being imported — e.g. build_runner or other codegen runners — should be listed via --ignore:

pubspec_doctor --ignore build_runner

Roadmap

• Config file (pubspec_doctor.yaml) for permanent ignores.
• Auto-detect codegen packages (build_runner, freezed, …) as used.
• Under-/over-promotion checks (dep that should be a dev_dependency and vice versa).
• Dart SDK compatibility check for the latest release of each dependency.

License

MIT