depchk

Python dependency version checker for Poetry projects. Analyzes pyproject.toml and provides upgrade recommendations with risk assessment and Python compatibility checks.

What It Does

• Checks PyPI for the latest most compatible versions of your dependencies
• Risk-scores each update (HIGH/MEDIUM/LOW) based on version jumps and Python compatibility
• Respects constraints from local path dependencies (monorepos, git submodules)
• Validates recommended versions and their support for your target Python version
• Creates a backup before modifying your pyproject.toml
• JSON output for automation and CI/CD

Quick Start

Install Depchk

Install Depchk with pipx to run it as a standalone tool without affecting your system Python:

pipx install depchk

Or with pip in a virtual environment:

pip install depchk

Tip: pipx is recommended for global CLI tools as it provides isolated environments.

Or with Poetry (for development):

git clone https://github.com/bulletinmybeard/depchk.git
cd depchk
poetry install

# Analyze your project
depchk /path/to/pyproject.toml

# Preview what will change (creates pyproject.toml.updated.toml)
depchk

# Apply updates directly (creates backup first)
depchk --update-source-file

CLI Commands

Note: --json and --verbose are mutually exclusive. Using both will exit with a JSON error.

Automation

depchk supports JSON output for scripting and CI/CD. All JSON responses use a standardized envelope:

# Check response status
depchk --json | jq '.status'
# Output: "success"

# Get update recommendations
depchk --json | jq '.data.updates'

# Check summary programmatically
depchk --json | jq '.data.summary'

# Test against a different Python version
depchk --target-python "^3.13" --json

JSON Response Structure:

{
  "status": "success",
  "data": {
    "updates": {"httpx": "^0.28.1", ...},
    "summary": {"analyzed": 15, "updated": 8, ...},
    "report": [...]
  }
}

Error responses use the same envelope:

{
  "status": "error",
  "error": {"code": "incompatible_flags", "message": "..."}
}

Configuration

depchk uses a ~/.depchk/config.yaml file for persistent settings:

analysis:
  cache_ttl_hours: 24
  allow_prerelease: false

Config file locations (checked in order):

1. Project directory: ./config.yaml
2. User home: ~/.depchk/config.yaml

Override with environment variables: DEPCHK_CACHE_TTL, DEPCHK_ALLOW_PRERELEASE.

Priority: CLI flags > Environment variables > Config file > Defaults

Example Output

+------------------------------------------+
| Dependency Analysis Report               |
| Python Version: ^3.12                    |
+------------------------------------------+

Summary

  * Analyzed: 15
  * Updates available: 8
  * Skipped: 2

Recommended Updates

| Package   | Current | ->  | Recommended | Python    | Risk |
|-----------|---------|-----|-------------|-----------|------|
| httpx     | ^0.25.0 | ->  | ^0.28.1     | 3.8->3.13 | MED  |
| fastapi   | ^0.115  | ->  | ^0.118.3    | 3.8->3.13 | LOW  |

! Risk Factors:
  * httpx:
    - Minor version jump (^0.25.0 -> ^0.28.1)

my-company/
+-- api/pyproject.toml           # python = "^3.12", httpx = "^0.27.0"
+-- shared-utils/pyproject.toml  # python = "^3.12", httpx = "^0.25.0" <- ceiling

depchk() {
    local project_dir="$HOME/path/to/depchk"
    local original_dir="$PWD"

    if [[ ! -d "$project_dir" ]]; then
        echo "Error: depchk project not found at $project_dir"
        return 1
    fi

    if [[ $# -eq 0 ]] || [[ "$1" == -* ]]; then
        (cd "$project_dir" && poetry run depchk "$original_dir/pyproject.toml" "$@")
    else
        (cd "$project_dir" && poetry run depchk "$@")
    fi
}

[ -f "$HOME/depchk_shell.sh" ] && source "$HOME/depchk_shell.sh"

Risk Assessment

Each update is scored based on:

• Version jump impact: Major > Minor > Patch
• Python compatibility: Checks requires_python metadata from PyPI
• Classifier data: Extracts tested Python versions

Confidence levels:

• LOW: Patch/minor updates with full Python compatibility
• MEDIUM: Minor version jumps or limited compatibility data
• HIGH: Major updates with potential compatibility issues

Requirements

• Python 3.12+
• Poetry for dependency management
• A Poetry project (pyproject.toml with [tool.poetry] section)

Links

• Configuration Example
• Changelog

License

MIT License - see the LICENSE file for details.