pub_doctor #

A fast dependency health analyzer for Dart and Flutter projects.

pub_doctor scans your pubspec.yaml, analyzes dependency metadata, and detects risky or poorly maintained packages before they cause build failures or compatibility issues.

It helps you maintain stable builds, enforce dependency health, and make safer upgrade decisions locally and in CI.

Overview #

Managing dependencies in Dart and Flutter projects becomes difficult over time:

• packages stop being maintained
• versions become outdated
• updates introduce breaking changes
• security or stability risks go unnoticed

pub_doctor analyzes dependency ecosystem signals and generates a risk score for each package so you can detect problems early.

No project source code is analyzed only public package metadata.

Features #

• Dependency risk scoring
• Maintenance activity analysis
• Version freshness detection
• Update availability detection
• CI automation support
• Fast and lightweight execution
• Offline support with caching
• Machine-readable JSON output
• No code analysis

What pub_doctor Checks #

• Package maintenance activity
• Version freshness
• Ecosystem risk signals
• Update availability
• Overall dependency risk score

pub_doctor evaluates dependency health using public package and repository signals.

Installation #

Global installation (recommended) #

dart pub global activate pub_doctor

Then run:

pub_doctor

Add to project (dev dependency) #

dev_dependencies:
  pub_doctor: ^0.0.1

Run with:

dart run pub_doctor

Run without installing #

dart run pub_doctor

Quick Start #

Run pub_doctor inside any Dart or Flutter project:

pub_doctor

This scans the pubspec.yaml in the current directory and analyzes all dependencies.

Usage #

Basic commands #

Analyze dependencies #

pub_doctor

Scans project dependencies and prints health results.

Analyze including dev dependencies #

pub_doctor --dev

Output machine-readable JSON #

pub_doctor --json

Useful for CI or automation.

Enable CI mode #

pub_doctor --ci

Fails with a non-zero exit code when high-risk dependencies are detected.

Auto-update safe dependencies (New) #

pub_doctor update

Automatically resolves and upgrades all your packages in pubspec.yaml to their highest mutually compatible versions to fix inter-compatibility conflicts.

Run using cached data only #

pub_doctor --offline

No network requests.

Show detailed output #

pub_doctor --verbose

Shows all scoring signals.

Show help #

pub_doctor --help

Example Output #

$ pub_doctor

Analyzing dependencies...

✓ http
Risk Score: 2.1 (Healthy)
Latest: 1.2.0
Status: Actively maintained

⚠ some_old_package
Risk Score: 8.4 (High Risk)
Latest: 0.9.0
No commits for 412 days — maintenance appears inactive

Overall Project Risk Score: 5.3 (Moderate)

Risk Scoring #

Each dependency receives a risk score from 0 → 10.

Signals used #

• Time since last release
• Repository commit activity
• Version lag from latest
• Ecosystem maintenance indicators
• Update frequency

The score is heuristic and explainable. It helps guide decisions not replace engineering judgment.

CI Integration (Recommended) #

pub_doctor can run automatically in CI pipelines and fail builds when risky dependencies are detected.

This ensures dependency health enforcement across teams.

GitHub Actions Example #

name: Dependency Health Check

on: [push, pull_request]

jobs:
  pub_doctor:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1

      - run: dart pub global activate pub_doctor
      - run: pub_doctor --ci

CI Exit Codes #

Typical Workflow #

During local development #

pub_doctor

Check dependency health before committing.

Before upgrading dependencies #

flutter pub upgrade
pub_doctor

Detect risks introduced by upgrades.

Continuous Integration #

Run pub_doctor automatically to prevent risky dependencies from reaching production.

Performance #

• Fast analysis (usually < 2 seconds)
• Cached results for repeated runs
• Minimal network usage
• Parallel dependency checks
• Works locally and in CI environments

Caching #

To improve performance:

• Dependency metadata is cached locally
• Cache expires automatically
• --offline uses cached results only

Privacy & Security #

• No source code is uploaded
• Only public dependency metadata is analyzed
• No tracking or telemetry
• Safe for private projects

Limitations #

• Only public package metadata is analyzed
• Transitive dependency scanning is limited
• Private repositories may provide limited signals
• Risk score is heuristic and not a guarantee of quality

When Should You Use pub_doctor? #

Use pub_doctor if you want:

• Stable builds
• Early dependency risk detection
• Safer upgrades
• Automated dependency health checks
• CI dependency enforcement
• Better long-term project stability