pyupcheck

Check if upgrading a Python dependency will break your code.

$ pyupcheck check-all

Found 12 dependencies to check

flask 2.3.3 -> 3.1.3  OK (15 usages safe)
requests 2.28.0 -> 2.34.2  2 BREAKING
  x src/api.py:23  resp = requests.get(url, verify=False)
    Removed: `verify` parameter no longer accepted
django 4.2.0 -> 5.0.6  1 deprecated
  ! core/models.py:8  from django.utils import timezone
    Deprecated: use datetime.timezone instead

2 breaking | 1 deprecated across 12 packages

Install

pip install pyupcheck

Commands

check - check one package

pyupcheck check flask 3.0.0        # against specific version
pyupcheck check flask              # against latest

check-all - check every dependency

Reads requirements.txt and pyproject.toml (PEP 621 and Poetry), checks every dependency against its latest version.

pyupcheck check-all
pyupcheck check-all --format html -o report.html

outdated - list stale dependencies

pyupcheck outdated

Flags major version bumps separately since they carry the most risk.

diff - changelog diff between versions

See breaking/deprecated changes between any two versions without scanning code:

pyupcheck diff django 4.2.0 5.0.0

scan - list your usages of a package

pyupcheck scan requests

versions and cache-clear

pyupcheck versions flask
pyupcheck cache-clear

Output formats

pyupcheck check flask -f json          # machine-readable
pyupcheck check flask -f md -o r.md   # markdown report
pyupcheck check flask -f html -o r.html # styled HTML report

CI integration

Exit code is 1 when the --fail-on condition is met:

pyupcheck check-all --fail-on breaking     # default
pyupcheck check-all --fail-on deprecated   # stricter
pyupcheck check-all --fail-on any          # strictest
pyupcheck check-all --fail-on never        # report only

GitHub Actions example:

- name: Check dependency upgrades
  run: |
    pip install pyupcheck
    pyupcheck check-all --fail-on breaking --quiet

Pre-commit hook (.pre-commit-config.yaml):

- repo: local
  hooks:
    - id: pyupcheck
      name: pyupcheck
      entry: pyupcheck check-all --quiet
      language: system
      pass_filenames: false

Configuration

pyproject.toml:

[tool.pyupcheck]
exclude = ["migrations", "legacy"]
ignore = ["internal-package"]
fail_on = "breaking"
min_severity = "deprecated"
cache = true

Or .pyupcheckignore:

migrations/          # trailing slash = directory
legacy/
internal-package     # no slash = package to skip

Features

• AST-based scanning: imports, from-imports, aliases, attribute chains, calls
• Jupyter notebook (.ipynb) scanning, magics stripped automatically
• Changelog sources: GitHub releases, raw changelog files, PyPI descriptions
• 24h response cache (--no-cache to bypass, cache-clear to wipe)
• Severity filtering with --min-severity
• Quiet mode (-q) for hooks and scripts

Limitations

• Changelog parsing relies on maintainers writing structured changelogs
• Dynamic attribute access (getattr(pkg, name)) is not detected
• GitHub API is rate limited to 60 req/hr unauthenticated; pass --github-token or set GITHUB_TOKEN for higher limits

Contributing

Contributions are welcome. Here is how to get started:

git clone https://github.com/AgbaDev/pyupcheck.git
cd pyupcheck
pip install -e ".[dev]"

Things that would genuinely improve the tool:

• Better changelog parsing for packages that use unconventional formats (e.g. Sphinx-based changelogs, HISTORY files)
• Support for setup.cfg and setup.py dependency parsing
• Detection of dynamic attribute access patterns (getattr, __import__)
• pip-tools and conda lockfile support
• A --watch mode that monitors your lockfile for changes and alerts on risky upgrades
• Test coverage

To contribute, open an issue describing what you want to work on, then submit a pull request. Please include a short test or example showing the bug or feature.

If you find a package whose changelog pyupcheck fails to parse correctly, open an issue with the package name and version range. That is the most common and most impactful thing to fix.

License

MIT