Linux online course

Using apt-cache to Search and Inspect Debian Packages

Learn how apt-cache searches local APT indexes, displays package metadata, inspects dependencies, finds reverse dependencies, lists package names, and diagnoses unmet dependencies.

apt-cache is a command-line inspection tool in the APT ecosystem. APT, the Advanced Package Tool, manages software packages on Debian, Ubuntu, and related Linux distributions.

The commands in this lesson query locally stored package metadata. They do not install, remove, or upgrade software. This makes them useful when you want to investigate a package before changing the system.

What apt-cache Reads

A package repository is a software source that publishes packages and metadata for APT clients. Your repository sources are configured traditionally in /etc/apt/sources.list and commonly in additional files under /etc/apt/sources.list.d/.

APT downloads repository package indexes when you run an index update:

sudo apt-get update

A package index is local metadata describing package names, versions, architectures, descriptions, origins, and dependency relationships. After the indexes are downloaded, apt-cache queries those local files. A normal lookup does not contact a repository.

Because the information is local, results can be stale. A package released yesterday may not appear until the indexes are refreshed, and an old version may remain visible until newer metadata is downloaded.

It is important to distinguish two kinds of information:

• APT package metadata: packages and versions available from configured repository indexes.
• Installed package state: packages currently recorded as installed in the system package database.

Modern workflows often use apt search, apt show, and apt list because their output is friendlier for interactive use. apt-cache remains widely available and is especially useful for cache-oriented queries and dependency inspection.

apt-cache Subcommands at a Glance

Searching for Packages

Use apt-cache search when you know what a program does but do not know its package name:

apt-cache search network mapper

The search examines package names and descriptions in the local cache. A multiword query can help describe a purpose rather than guessing an exact name. In this example, the results may identify nmap as a network-mapping utility.

After selecting a likely result, inspect it:

apt-cache search network mapper
apt-cache showpkg nmap

Broad searches can produce many results. Add a more specific term or pipe the output through a text filter:

apt-cache search network | grep -i map

The shell pipe sends the search output to grep, which keeps lines containing the requested text. Use less when you want to paginate a long result:

apt-cache search network | less

Search results depend on the enabled repositories, distribution release, architecture, and freshness of the indexes. A search does not prove that a package is installed.

Viewing Package Information with showpkg

apt-cache showpkg PACKAGE_NAME is a historical package-information command that exposes several sections of cache data:

apt-cache showpkg nmap

• Available versions: versions known from configured repositories.
• Dependency data: relationships declared by the package and its versions.
• Reverse dependencies: packages that refer to the selected package.
• Package-list source information: information about the indexes and sources contributing the record.

Multiple available versions can exist when multiple repositories or releases are configured. The presence of a version in this output does not mean that version is installed or that APT will choose it for the next transaction.

For a more directly readable control record, use:

apt-cache show nmap
apt show nmap

These commands commonly display fields such as package name, version, architecture, description, dependencies, and repository-related details.

If showpkg reports no matching package, check the spelling, search for part of the name, and refresh the indexes:

apt-cache search nmap
sudo apt-get update
apt-cache showpkg nmap

If the package still cannot be found, it may not be supplied for your release or architecture, or the relevant repository component may not be enabled.

Inspecting Package-Cache Statistics

Run apt-cache stats to see aggregate information about the local metadata cache:

apt-cache stats

Depending on the APT version, the report includes figures such as:

• Total package names known to the cache.
• Package structures and available versions.
• Dependency relationships.
• Description records and related metadata.

These figures describe cached repository metadata, not simply the software installed on the computer. They can help confirm that package lists exist, compare the cache before and after an index refresh, and provide basic diagnostic information when searches unexpectedly return little or no data.

Checking for Unmet Dependencies

apt-cache unmet reports dependency relationships that the local cache considers unsatisfied or unresolved:

apt-cache unmet

A correctly configured and consistent system frequently produces no useful output. That is normally a good sign, but an empty report is not a complete proof that every possible installation transaction will succeed.

This is a cache-based diagnostic. It does not replace package repair commands or a full transaction simulation. If dependency problems are reported, refresh indexes and investigate repository consistency, interrupted operations, held packages, and version conflicts.

sudo apt-get update
apt-cache unmet
apt-get -s install PACKAGE_NAME

The -s option simulates an installation and does not apply the transaction. A repair command such as apt-get -f install can change system state, so review its proposed actions carefully before confirming it.

Viewing Dependencies with depends

Use apt-cache depends to inspect relationships declared by a package:

apt-cache depends nmap

Common labels include the following:

A virtual package is a capability name that one or more real packages can provide. For example, a package may depend on an interface rather than one specific implementation. The dependency output helps reveal these provider choices.

Declared relationships are not necessarily the exact final installation transaction. APT also considers architecture, versions, repository priorities, already installed packages, conflicts, and configuration when resolving an operation.

Finding Reverse Dependencies with rdepends

A reverse dependency is a package that declares a relationship on another package. Query them with:

apt-cache rdepends libssl3

This is useful before removing, replacing, or changing a library, service, or shared component. The output can show which packages may be affected by a change.

Reverse-dependency results come from packages known in the configured repository indexes. They can include packages that are not installed locally. Treat the result as a repository-wide relationship map, not as a list of currently running consumers.

When planning a removal, cross-check important results against the installed package database and simulate the proposed transaction before making changes.

Listing Package Names with pkgnames

apt-cache pkgnames lists package names known to the local APT cache:

apt-cache pkgnames

This can produce a very long list. Supply an optional prefix to limit the output to names beginning with that prefix:

apt-cache pkgnames doc

The command lists repository-known names, not only packages installed on the machine. To inspect installed software instead, use:

apt list --installed
dpkg-query -W

Package Cache Results versus Installed State

Safe Usage and Interpreting Output

The featured apt-cache operations are read-only queries and generally do not require administrator privileges. The exception is not the query itself but the index refresh: updating repository metadata normally requires sudo.

Output varies according to:

• Distribution release and repository components.
• Enabled source entries in /etc/apt/sources.list and /etc/apt/sources.list.d/.
• CPU architecture and enabled foreign architectures.
• How recently apt or apt-get update downloaded indexes.
• Package versions, transitions, virtual packages, and repository priorities.

Use less for long output and grep for focused text searches:

apt-cache rdepends libssl3 | less
apt-cache depends nmap | grep -E 'Depends|Recommends|Provides'

Before installing a package or selecting a particular version, verify the current metadata with apt show, review the candidate version with current APT tooling, and use a simulation when the transaction matters:

apt show PACKAGE_NAME
apt-get -s install PACKAGE_NAME

Troubleshooting Common Results

A search does not find an expected package

• Refresh the local indexes with sudo apt-get update.
• Review whether the repository and relevant component are enabled.
• Try a narrower package name or alternate descriptive terms.
• Confirm that the package supports your distribution release and architecture.

showpkg reports no matching package

• Check for a spelling mistake.
• Search with part of the name using apt-cache search.
• Refresh the indexes.
• Check repository source configuration and availability.

pkgnames shows packages that are not installed

This is expected: pkgnames reads repository indexes. Use apt list --installed or dpkg-query to inspect the installed-package database.

rdepends produces a large list

The list can include every repository-known consumer, including packages not installed on the machine. Cross-check individual packages against installed state before deciding whether a removal is safe.

unmet reports dependency problems

Possible causes include mixed repositories, interrupted package operations, held packages, version conflicts, or stale metadata. Refresh the indexes, inspect repository release consistency, review holds and package policy, and simulate the intended operation. Use repair commands such as apt-get -f install only after reviewing their proposed changes.

A Practical Investigation Workflow

1. Refresh package indexes if the search results may be stale.
2. Search by purpose when the package name is unknown.
3. Inspect the candidate with apt-cache showpkg or the more readable apt-cache show.
4. Use apt-cache depends to understand required and optional relationships.
5. Use apt-cache rdepends before changing a shared library or service.
6. Use apt-get -s to simulate an installation or removal when the consequences matter.
7. Use apt-cache unmet and apt-cache stats as cache-level diagnostics.

For broader APT command usage, see the Linux command reference. To understand how a shell resolves an executable name, see showing the full path of shell commands.

Key Exam Notes

• apt-cache reads local APT metadata; it normally does not contact repositories during a query.
• sudo apt-get update refreshes the indexes that supply that metadata.
• apt-cache pkgnames lists cache-known package names, not installed packages.
• apt-cache depends shows relationships declared by a package; rdepends shows packages that refer to it.
• apt-cache unmet is a cache-based diagnostic, not a replacement for transaction simulation or package repair.
• Available versions and repository relationships do not by themselves identify the installed version or guarantee the exact result of a future transaction.