depkeeper

Safe, conflict-aware dependency updates for pip requirements files.

depkeeper analyses requirements.txt-style files, computes a safe upgrade target for every requirement, cross-validates those targets against each other, and rewrites the file in place — without discarding the constraints you authored.

It is a single-purpose CLI. It does not manage virtual environments, install packages, replace pip, or introduce a lock file format.

Contents

• Why depkeeper · What it guarantees
• Install · Quick start · Commands
• Configuration · Common workflows
• Architecture · Limitations
• Troubleshooting · Documentation · Contributing

Why depkeeper

pip list --outdated reports the latest version, which is frequently a major release that will break your build. Lock-file tools solve this properly but require adopting a new workflow and file format.

depkeeper fills the gap. It answers one question, precisely:

What is the largest upgrade I can take for each requirement without crossing a major version, without breaking Python compatibility, without violating the constraints I declared, and without conflicting with the other packages in my file?

Then it applies the answer to the file you already have.

What it guarantees

These are enforced in code, not advisory:

The trade-off is explicit: depkeeper is deliberately conservative. It will never propose the major upgrade you eventually need.

Install

python -m pip install depkeeper     # into the project's environment (recommended)
pipx install depkeeper              # isolated global tool

Requires Python 3.8+.

[!IMPORTANT] depkeeper filters candidate versions against the interpreter it runs on, not your project's. Installing it on 3.8 while your service targets 3.12 makes recommendations silently conservative. Install it into the project environment, or use pipx install --python python3.12 depkeeper.

Verify:

depkeeper --version        # depkeeper 0.1.1
python -m depkeeper --help # equivalent module entry point

Quick start

Given this file:

requests==2.28.0
flask>=2.0,<2.3
celery[redis]>=5.0,<6.0
click~=8.0
certifi
urllib3==1.26.0

1. Inspect (read-only, never writes):

$ depkeeper check
┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃   Status   ┃ Package  ┃ Current ┃  Latest   ┃ Recommended ┃ Update Type ┃ Conflicts ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ [OUTDATED] │ requests │ 2.28.0  │  2.34.2   │   2.34.2    │    minor    │ -         │
│ [OUTDATED] │ flask    │   2.0   │   3.1.3   │    2.2.5    │    minor    │ -         │
│ [OUTDATED] │ celery   │   5.0   │   5.6.3   │    5.6.3    │    minor    │ -         │
│ [OUTDATED] │ click    │   8.0   │   8.4.2   │    8.4.2    │    minor    │ -         │
│    [OK]    │ certifi  │    -    │ 2026.7.22 │      -      │      -      │ -         │
│ [OUTDATED] │ urllib3  │ 1.26.0  │   2.7.0   │   1.26.20   │    patch    │ -         │
└────────────┴──────────┴─────────┴───────────┴─────────────┴─────────────┴───────────┘
[WARNING] 5 package(s) have updates available

2. Preview the exact write:

depkeeper update --dry-run

3. Apply:

$ depkeeper update --backup
Update 6 packages? (y, n) [y]: y
[OK] ✓ Successfully updated 6 package(s)

requests==2.34.2
flask>=2.2.5,<2.3          # your <2.3 cap held — latest is 3.1.3
celery[redis]>=5.6.3,<6.0  # extra and upper bound preserved
click~=8.4                 # compatible-release form preserved
certifi==2026.7.22         # unversioned requirement gained a pin
urllib3==1.26.20           # major boundary held — latest is 2.7.0

4. Verify — this step is not optional:

python -m pip install -r requirements.txt && pytest

depkeeper validates the packages you declared against each other. It does not expand the transitive graph, so pip remains the authority on whether the set installs.

Commands

depkeeper check [FILE]

Read-only analysis. Never modifies the filesystem. Exits 0 on success regardless of findings.

depkeeper update [FILE]

Applies recommended versions in place.

Global options

-c/--config PATH · -v / -vv (INFO / DEBUG, always on stderr) · --color/--no-color · --version · -h/--help

Global options must precede the subcommand: depkeeper -v check, not depkeeper check -v.

Full specification: CLI reference.

Exit codes

Gate automation on the JSON payload, never on check's exit code.

Configuration

Two settings are persistable, in depkeeper.toml or pyproject.toml. Everything else is a per-invocation flag, deliberately — options that change what gets written stay visible in the command line.

# depkeeper.toml
[depkeeper]
check_conflicts = true            # cross-package conflict resolution
strict_version_matching = false   # treat only `==` as a current version

# pyproject.toml
[tool.depkeeper]
check_conflicts = true
strict_version_matching = false

Precedence: defaults < config file < CLI flag. Unknown keys and wrong types are hard errors. Discovery is limited to the current working directory (not recursive).

Environment: DEPKEEPER_CONFIG, DEPKEEPER_COLOR, NO_COLOR, CI, plus httpx's HTTPS_PROXY / SSL_CERT_FILE.

Common workflows

Daily

depkeeper check --outdated-only
depkeeper update --dry-run
depkeeper update --backup && pip install -r requirements.txt && pytest

One package at a time (keeps regressions bisectable)

depkeeper update -p django -y && pytest

Application release — freeze to exact versions

depkeeper update --pin --backup

CI drift report — stdout stays parseable even with -v

depkeeper -v check --format json --no-check-conflicts > report.json 2> depkeeper.log
jq '[.[] | select(.status == "outdated")] | length' report.json

Multi-file projects — -r includes are followed and rewritten

depkeeper update requirements/dev.txt --dry-run   # also writes base.txt

Hash-pinned files — depkeeper refuses these by default

depkeeper update --allow-hash-removal -y
pip-compile --generate-hashes requirements.in     # regenerate; not optional

More: User guide · CI/CD integration

Architecture

Synchronous CLI around an asynchronous core. No daemon, no persistent state, no cache directory.

requirements.txt
      │
      ▼
RequirementsParser ──► PyPIDataStore ──► VersionChecker ──► DependencyAnalyzer ──┐
  (text → model)      (one HTTP call     (per-package      (cross-package         │
                       per package)       target version)   consistency)          │
                                                                                  ▼
                                                             renderer (table/simple/json)
                                                             writer (atomic, rollback-safe)

See ARCHITECTURE.md for the contributor-facing map, or the architecture deep dive for design decisions, concurrency model and error propagation.

Limitations

Honest, verified, and documented in full at Known limitations. The ones most likely to affect you:

• Not a resolver. The transitive graph is not expanded. Always pip install and test.
• Only pypi.org is queried. --index-url lines are parsed and ignored; private packages report as errors.
• Calendar versions hit the major boundary. certifi 2023.x never auto-bumps to 2024.x.
• Major upgrades are yours to make. Raise the floor by hand, then let depkeeper continue.
• Backslash line continuations are not parsed, so default pip-compile --generate-hashes output is unreadable to depkeeper.
• No runtime tuning. Timeouts, retries and concurrency are constants; override them via the Python API if you must.

Troubleshooting

Start here:

depkeeper -vv check --format json > report.json 2> debug.log

debug.log names the file parsed, the effective configuration, every HTTP retry and every resolution decision.

Full guide: Troubleshooting

Documentation

Published at rahulkaushal04.github.io/depkeeper.

Repository documents: ARCHITECTURE.md · CONTRIBUTING.md · CHANGELOG.md · SECURITY.md · SUPPORT.md · CODE_OF_CONDUCT.md

Project status

Version 0.1.1, classified Development Status :: 4 - Beta.

The write path is defensive — atomic replacement, two-phase commit, rollback, optional backups — and behaviour is documented and covered by tests across Linux, macOS and Windows on Python 3.8–3.12. Pin the version in automation: recommendation logic is a behavioural contract, and a version bump can legitimately change an update plan.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, and read the system invariants before changing anything in core/.

git clone https://github.com/rahulkaushal04/depkeeper.git
cd depkeeper
pip install -e ".[dev,docs]"
pre-commit install

python -m pytest tests -q --no-cov
python -m mypy depkeeper --python-version 3.13

Report vulnerabilities privately — see SECURITY.md, never a public issue.

License

Apache License 2.0. Copyright 2025-2026 Rahul Kaushal.

Built with Click, Rich, httpx and packaging — the last of which is why depkeeper agrees with pip about what a version means.