Inspect APT Packages and Dependencies with apt-cache

apt-cache answers every "what would this actually pull in" question without installing, removing or upgrading a single package. This guide covers searching APT metadata, checking a package's selected version, and tracing its dependencies. Allow about ten minutes if you already know the package name, or fifteen if you are investigating an unfamiliar one. The examples were checked with APT 2.8.3.

You need a shell and the apt package. These commands normally run as your ordinary user. They read the local APT cache, which may be regenerated when it is missing or out of date, but apt-cache never installs or removes anything. Its information can still be stale: package lists are only refreshed by a separate apt update operation.

1. Confirm the installed version

Start by checking which implementation and package version you are using:

$ apt-cache --version
apt 2.8.3 (amd64)
$ dpkg-query -W -f='${Package} ${Version}\n' apt
apt 2.8.3

The manpage read for this guide is the APT 2.8.3 version dated 14 March 2024. Option details and output can differ between APT releases, so keep the version beside any diagnostic report.

2. Search package names and descriptions

search accepts POSIX regular expressions and searches package names and descriptions. Quote patterns so the shell does not reinterpret them:

$ apt-cache search 'text editor'
... matching package names and short descriptions ...

For a narrower package-name search, use --names-only. It avoids matches buried in long descriptions and is useful when you know part of the name:

$ apt-cache --names-only search '^apt-'
apt-config-icons - APT configuration snippet to enable icon downloads
apt-doc - documentation for APT
apt-listchanges - package change history notification tool

Several search arguments are combined as patterns, so adding another pattern narrows the result rather than starting an unrelated second search. A match describes metadata in the local cache; it does not prove the package is installed or currently downloadable.

3. Read one package record

Use show for the package record APT knows about. The default can include all available versions, useful for comparing repositories but noisy during a quick check. Add --no-all-versions to display only the candidate version:

$ apt-cache show --no-all-versions apt | sed -n '1,16p'
Package: apt
Priority: important
Section: admin
Installed-Size: 4108
Maintainer: Ubuntu Developers <[email protected]>
Architecture: amd64
Version: 2.8.3
Recommends: ca-certificates
Replaces: apt-transport-https (<< 1.5~alpha4~)
Suggests: apt-doc, aptitude | synaptic | wajig
Provides: apt-transport-https (= 2.8.3)

Use this output to inspect fields such as Version, Architecture, Depends, Recommends, Conflicts and Breaks. It is metadata, not an instruction to install the package.

To inspect a particular version, append =VERSION; to ask about a target release, append /RELEASE. Copy the exact version or release name from your own cache rather than guessing it.

4. Check the installed and candidate versions

policy is the quickest way to explain why APT would select a version. With a package name it shows the installed version, candidate version and version table:

$ apt-cache policy apt
apt:
  Installed: 2.8.3
  Candidate: 2.8.3
  Version table:
 *** 2.8.3 500
        500 ... noble-updates ...
        100 /var/lib/dpkg/status
     2.7.14build2 500
        500 ... noble ...

The URLs and repository names shown are host-specific. The comparison that usually matters is Installed versus Candidate, then the priorities and origins in the table. A package can have a candidate even when it is not installed. With no package argument, policy prints priorities for the configured sources.

5. Trace direct dependencies

Use depends to see each dependency and the packages that can satisfy it:

$ apt-cache --important depends apt
apt
 |Depends: base-passwd
  Depends: adduser
  Depends: gpgv
  Depends: libapt-pkg6.0t64
  Depends: ubuntu-keyring
  Depends: libc6

The --important option limits this view to Depends and Pre-Depends. Without it, APT can also show recommendations, suggestions, conflicts and breaks. An indented alternative is another way to satisfy a dependency, not a second package this command has installed.

For the reverse question, use rdepends:

$ apt-cache rdepends libssl3
libssl3
Reverse Depends:
  ... packages which depend on libssl3 ...

Use --installed when you only want installed packages in a dependency view, and --recurse when you need the transitive tree. Recursive output grows quickly, so start with one package and add those flags only when the direct result is not enough.

6. List versions and package names

madison presents available versions in a compact table, handy when a policy result is hard to scan:

$ apt-cache madison apt
       apt |      2.8.3 | ... noble-updates ...
       apt | 2.7.14build2 | ... noble ...

It reports the architecture for which APT retrieved package lists, not every architecture known to an archive. For shell completion or a quick name list, use pkgnames with an optional prefix:

$ apt-cache pkgnames apt- | sed -n '1,5p'
apt-cacher-ng
apt-transport-artifact-registry
apt-cudf
apt-rdepends
apt-btrfs-snapshot

A name in this list is not necessarily installed, installable or downloadable. Virtual packages can appear too. Treat it as a name index, then use show or policy for actual evidence about a specific package.

7. Handle errors without changing state

APT uses exit status 0 for normal operation and decimal 100 for an error. Capture the status immediately if a script needs to distinguish a failed query:

if apt-cache show 'PACKAGE_NAME' >/tmp/apt-cache-record 2>/tmp/apt-cache-error; then
    sed -n '1,20p' /tmp/apt-cache-record
else
    status=$?
    printf 'apt-cache failed with status %s\n' "$status" >&2
    sed -n '1,20p' /tmp/apt-cache-error >&2
    exit "$status"
fi

Replace PACKAGE_NAME with a package name you intend to inspect. The temporary files are ordinary output captures; remove them after review if they hold information you do not want to keep. Never treat an empty search result as proof a package does not exist anywhere: it may only be absent from this machine's cached lists.