Basic Usage¶

This page explains how to read what depkeeper reports. It is the reference for interpreting a run; the mechanics of each command live in Checking for updates and Updating dependencies.

The two commands¶

Both accept an optional FILE argument. The file must exist and must not be a directory; otherwise Click rejects it with exit code 2 before depkeeper runs.

depkeeper check requirements-dev.txt
depkeeper update requirements/prod.txt

Version vocabulary¶

Four version slots appear throughout the output. Confusing them is the single most common source of misread reports.

The invariant after a run with conflict checking enabled is that the recommended version shown in the report is exactly the version update writes. See Conflict resolution → Result invariant.

Current-version inference¶

depkeeper reads a range as a statement about where you are today:

This matters because the inferred current version establishes the major boundary. django>=3.2,<5.0 anchors to major 3, so depkeeper caps it at the newest 3.x even though 4.x satisfies the declared range.

Pass --strict-version-matching to disable inference: only a sole == counts as a current version. Everything else is then treated as "not installed", which changes both the status and the boundary. See Strict version matching.

Statuses¶

Table format statuses¶

[INCOMP] deliberately outranks [CONFLICT]: a required downgrade means the version you declared cannot be used at all, which you must see first.

JSON / simple statuses¶

The machine formats use a different, finer-grained ladder:

The table format¶

--format table (the default) renders a Rich table with eight columns:

A blank Recommended cell means "same as current" — it is suppressed to reduce noise, not because no recommendation exists.

The table format also prints the Resolution Summary (totals, convergence, per-package version changes) before the table whenever conflict checking is enabled.

The simple format¶

--format simple emits one status line per package plus indented detail lines. Rich markup is disabled for these lines, because a label such as [OUTDATED] would otherwise be interpreted as a style tag and swallowed.

[OUTDATED]   requests             2.28.0     → 2.34.2
       Python: installed: >=3.7, <4, latest: >=3.10, recommended: >=3.10
[OUTDATED]   flask                2.0        → 3.1.3      (recommended: 2.2.5)
       Python: latest: >=3.9, recommended: >=3.7
[INSTALL]    certifi              none       → 2026.7.22
       Python: latest: >=3.7

The arrow points at latest, not at the recommendation. When the two differ — because a major boundary, a declared cap or a conflict capped the upgrade — the recommendation is appended in parentheses. Conflicts appear as additional indented ⚠ Conflict: lines.

The JSON format¶

--format json prints a JSON array to stdout and nothing else. An empty result set still emits [], so a consumer such as jq never receives empty input.

[
  {
    "name": "flask",
    "status": "outdated",
    "versions": {
      "current": "2.0",
      "latest": "3.1.3",
      "recommended": "2.2.5"
    },
    "update_type": "minor",
    "python_requirements": {
      "latest": ">=3.9",
      "recommended": ">=3.7"
    }
  }
]

Only name and status are guaranteed present. Every other key is omitted when empty. The full schema, including the conflicts and error members, is in JSON output.

Output streams¶

This distinction matters for any scripted use:

Consequently this is safe, even with verbose logging:

depkeeper -vv check --format json | jq .

and this discards the diagnostics:

depkeeper check --format json 2>/dev/null | jq .

Errors always go to stderr regardless of format.

Common first-run surprises¶