Inspect APT packages and dependencies safely with apt-cache

You will finish with a small set of commands for searching APT metadata, checking the selected version of a package, and tracing dependencies without installing, removing or upgrading anything. The examples were checked with APT 2.8.3 on this machine. Allow about ten minutes if you already know the package name, or fifteen minutes if you are investigating an unfamiliar one.

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 does not perform package installation or removal. Its information can still be stale: package lists are acquired 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. This avoids matches 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 creating an unrelated second search. Remember that a match describes metadata in the local cache; it does not prove that the package is installed or currently downloadable.

3. Read one package record

Use show for the package record that APT knows about. The default can include all available versions, which is helpful when 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 are host-specific. The important comparison is usually Installed versus Candidate, followed by 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 relationships such as recommendations, suggestions, conflicts and breaks. An indented alternative represents another way to satisfy a dependency; it is not a second package that 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. Start with one package and add those flags only when the direct result is insufficient.

6. List versions and package names

madison presents available versions in a compact table, which is useful 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 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 reviewing if they contain information you do not want to retain. Never treat an empty search result as proof that a package does not exist everywhere: it may only be absent from this machine's cached lists.