Understanding apt-cache policy Output in Debian

The apt-cache policy command is a diagnostic tool on Debian-based operating systems that reveals how the APT package management system prioritizes and selects software versions. This article breaks down the information displayed by the command, explaining how it displays installed versions, installation candidates, repository sources, and APT pinning priorities to help system administrators troubleshoot package selection and repository behavior.

Package-Specific Policy Information

When executed with a package name (for example, apt-cache policy nginx), the command returns specific versioning details and the repository origin for that single package. The output consists of three primary components:

  • Installed: Displays the version of the package currently running on the system. If the package is not installed, this line displays (none).
  • Candidate: Shows the version that APT will select if you run apt install <package> or apt upgrade. APT determines this version based on package priority rules and version numbers.
  • Version Table: A chronological list of all versions of the package available to your system from configured repositories, alongside their pin priorities and origin URLs.

Reading the Version Table

Each entry in the Version Table contains critical metadata about an available package version:

  • Version Number: The explicit package version (such as 1.22.1-9). If an entry matches the currently installed version, it is typically marked with three asterisks (***).
  • Pin Priority Value: An integer (such as 500 or 100) indicating the weight APT assigns to that repository source.
  • Repository URL and Suite: The network location of the archive, followed by the suite (e.g., bookworm, bookworm-updates, or bookworm-backports) and component (e.g., main, contrib, or non-free).
  • Architecture and Origin: The CPU architecture (such as amd64) and release indicators defining where the metadata originates.

Global Repository and Pinning Policy

When executed without any arguments (apt-cache policy), the command prints the global APT priority table. This reveals how APT ranks your repositories against one another.

  • Priority Scores: It lists every configured repository along with its calculated pin priority (for example, standard repositories usually default to 500, while backports default to 100).
  • Repository Directives: It displays the metadata parameters used by the /etc/apt/preferences configuration file, such as release a= (archive), c= (component), v= (version), o= (origin), and l= (label).

Key Diagnostic Uses

Inspecting the output of apt-cache policy allows you to diagnose several common package management scenarios:

  • Unexpected Version Upgrades: If a package refuses to upgrade to the newest available release, the Candidate line and Pin Priority values will show whether an intentional or accidental pin (defined in /etc/apt/preferences) is holding the package back.
  • Third-Party Repository Verification: It confirms whether an external repository (such as Docker, NodeSource, or custom PPAs) is properly registered and providing the expected packages.
  • Distribution Transitions: It helps verify which packages originate from stable, testing, or unstable branches when running a mixed Debian system.