pubspec_doctor 0.3.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@v0
        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 pubspec_doctor
- run: dart pub global run pubspec_doctor --fail-on-stale

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

pubspec_doctor --json | jq '.unusedDependencies'

Configuration

Create pubspec_doctor.yaml next to your pubspec.yaml (or add a top-level pubspec_doctor: section to pubspec.yaml itself):

ignore:
  - some_internal_pkg
stale_days: 365
fail_on_stale: true

CLI flags take precedence over the config file; ignore lists are merged.

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.

Codegen and tool packages that are used without being imported are recognized automatically:

• generators whose companion package is referenced in code — freezed (via freezed_annotation), json_serializable (via json_annotation), drift_dev (via drift), riverpod_generator, mobx_codegen, and other common pairs;
• build_runner, when any declared package looks like a generator;
• tools configured through a top-level pubspec.yaml key, such as flutter_launcher_icons and flutter_native_splash.

Anything else that is intentionally unimported can be listed in the config ignore or via --ignore.

Roadmap

• 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