depwatch

Monitor your dependencies for staleness, abandonment, and vulnerabilities.

depwatch scans your Python project's dependencies and produces a health report covering version freshness, maintenance activity, and known security advisories. It outputs rich terminal tables by default and supports JSON for CI pipelines.

Example Output

 depwatch report for myproject
+-----------+-----------+--------+----------+--------+
| Package   | Installed | Latest | Last     | Health |
|           |           |        | Commit   |        |
+-----------+-----------+--------+----------+--------+
| requests  | 2.31.0    | 2.32.3 | 2 months | HEALTHY  |
| flask     | 2.3.2     | 3.1.0  | 3 weeks  | STALE    |
| pyjwt     | 2.6.0     | 2.9.0  | 8 months | AT_RISK  |
| urllib3   | 1.26.15   | 2.3.0  | 1 year   | CRITICAL |
+-----------+-----------+--------+----------+--------+
 4 dependencies scanned | 1 healthy | 1 stale | 1 at risk | 1 critical

Installation

pip install depwatch

Quick Start

# Scan the current project and display a rich table
depwatch

# Output results as JSON
depwatch --format json

# Run in CI mode (non-zero exit code if critical deps found)
depwatch --ci

Health Scoring

Each dependency is assigned a health status based on version lag, repository activity, and known vulnerabilities:

Status	Meaning
HEALTHY	Up to date or within one minor version; repository actively maintained
STALE	More than one minor version behind or no release in the last 6 months
AT_RISK	Multiple major versions behind or no repository activity in 6-12 months
CRITICAL	Known security vulnerabilities or project appears abandoned (12+ months inactive)

CI Usage

Add depwatch to your GitHub Actions workflow to catch dependency issues before they reach production:

name: Dependency Health Check

on:
  schedule:
    - cron: "0 8 * * 1" # every Monday at 08:00
  workflow_dispatch:

jobs:
  depwatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install depwatch
      - run: depwatch --ci

When --ci is passed, depwatch exits with code 1 if any dependency is rated CRITICAL, making it easy to fail a pipeline.

Options

Option	Description
--format	Output format: table (default) or json
--ci	CI mode: exit with code 1 on critical dependencies
--path	Path to the project directory (defaults to .)
--no-color	Disable rich color output
--version	Show depwatch version and exit
--help	Show help message and exit

License

MIT -- see LICENSE for details.