VMware ESXi and vSphere Cluster Management

apt-cache Command: Search and Inspect APT Package Metadata

Learn how to use apt-cache to search packages, inspect metadata and dependencies, find reverse dependencies, list package names, and review APT cache statistics.

What apt-cache does

APT means Advanced Package Tool, the package-management system used by Debian, Ubuntu, and many related Linux distributions. apt-cache is a command-line query tool within the APT toolset.

apt-cache reads package metadata stored in the local package cache. This metadata describes packages available from configured repositories, including names, descriptions, versions, dependencies, conflicts, and package relationships.

apt-cache is primarily an information tool. It does not install, remove, or upgrade software. Use commands such as apt install, apt remove, and apt upgrade for package-changing operations. Use apt-cache when you need to investigate package information before performing one of those operations.

How package metadata reaches apt-cache

A repository is a software source that publishes packages and package indexes. APT repository definitions are commonly configured in /etc/apt/sources.list and in files under /etc/apt/sources.list.d/.

Run apt update to download current repository indexes and refresh the local metadata:

sudo apt update

After this command completes, apt-cache can query the refreshed local indexes. If the indexes are stale, incomplete, or missing, searches may return outdated results, no results, or fewer versions than expected. Repository errors during apt update can also prevent particular sources from contributing metadata.

Package States and Data Sources

Configured repositories — Repository definitions in /etc/apt/sources.list and /etc/apt/sources.list.d/. Relevant operation: apt update. Common misunderstanding: configuring a source does not mean its packages are installed.

Refreshed package indexes — Repository-supplied metadata downloaded by apt update. Common misunderstanding: an index is metadata, not the package itself.

Packages known to the cache — Packages described by the local APT indexes. Relevant commands include apt-cache search and apt-cache pkgnames. Common misunderstanding: known packages are not necessarily installed.

Packages installed locally — Packages recorded as installed by the local package database. A package inventory can be queried with dpkg-query -W. Common misunderstanding: apt-cache output is not an installed-package inventory.

Searching for packages

Use apt-cache search when you know what a package should do but do not know its exact name. Searches match package names and package descriptions.

apt-cache search network mapper

The output usually contains a package name followed by a short description. Review the results and select a likely candidate for further inspection:

apt-cache search network mapper
apt-cache show nmap

Broad terms can produce a large result set. Narrow the search with more specific words, or filter the text output with a standard command such as grep:

apt-cache search network mapper | grep -i scanner

Search terms do not guarantee that every matching package is appropriate for your task. Treat search as discovery, then inspect the candidate's metadata, version, architecture, and relationships.

Viewing package information

Using apt-cache show

apt-cache show PACKAGE_NAME displays package control metadata in a relatively readable form. Depending on the package and enabled repositories, fields can include the package name, version, architecture, maintainer, description, dependencies, and related package information.

apt-cache show nmap

More than one record may appear when multiple versions are available from configured repositories. Read the version and repository-related fields carefully instead of assuming that the first visible record is the only available version.

Using apt-cache showpkg

apt-cache showpkg PACKAGE_NAME is more focused on package records and relationship data. It can show available versions, reverse dependencies, and dependency-related information in a format that is useful for examining the package cache.

apt-cache showpkg nmap

show is generally easier to read when you want a package description and control fields. showpkg is useful when you specifically need cache-level version and relationship details.

Inspecting cache statistics

Run apt-cache stats to summarize the local package metadata cache:

apt-cache stats

The report can include aggregate counts for package names, package structures, dependency relationships, provides entries, and other cache data. These figures help you understand the size and composition of the metadata database.

Checking unmet dependencies

apt-cache unmet reports unmet dependency relationships represented in the package cache:

apt-cache unmet

This is diagnostic metadata. It can help reveal relationships that the cache considers unsatisfied, but it does not by itself repair a broken installation or explain every transaction failure. Interpret the output alongside the exact error from the failing APT or dpkg operation.

If the result seems unexpected, refresh the indexes with sudo apt update. Also consider held packages, repository consistency, partially configured packages, and the specific operation that failed.

Displaying dependencies

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

apt-cache depends nmap

The output may contain required, optional, and negative relationships. A dependency can also name alternatives or a virtual package. A virtual package is a capability name that one or more real packages can provide.

Dependency Relationship Labels

Depends — A normal package requirement. It matters because the package generally cannot be installed or used correctly without a suitable provider.

PreDepends — A stricter requirement that must be configured before installation of the dependent package proceeds.

Recommends — A strongly suggested related package. It is commonly installed by default, but it is not the same as a hard Depends relationship.

Suggests — An optional enhancement or related package. It can add functionality without being required.

Conflicts — A package relationship that prevents the conflicting packages from being installed or used together in the relevant way.

Breaks — Indicates that a package version cannot safely coexist with another package or version until the package state changes.

Replaces — Indicates that package files or package ownership can replace those from another package, usually during an upgrade or transition.

Provides — Declares that a real package supplies a named capability, often a virtual package that another package can depend on.

When output shows alternatives, do not assume every alternative must be installed. A relationship such as “package A or package B” means a suitable provider may satisfy the requirement.

Finding reverse dependencies

A reverse dependency is a package that references the named package through a relationship such as Depends, Recommends, Conflicts, or another package relationship. Use:

apt-cache rdepends nmap

This is especially useful before removing or replacing a shared library, service, runtime, or other foundational package. It helps identify packages that may be affected by the change.

Do not treat every result as proof of a hard installation requirement. Read the relationship type and inspect the relevant package metadata. Some results can represent recommendations, suggestions, conflicts, or other references rather than mandatory dependencies.

Listing known package names

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

apt-cache pkgnames

The optional prefix limits results to names beginning with that string:

apt-cache pkgnames doc

This can help discover exact package names when you know the beginning of a name. The results come from cached repository metadata, so they are not limited to software installed on the system.

apt-cache subcommands at a glance

apt-cache Subcommands and Their Uses

search — Syntax: apt-cache search KEYWORD [KEYWORD ...]. Searches names and descriptions. Output: matching package names and summaries. Caveat: broad terms can return many results.

showpkg — Syntax: apt-cache showpkg PACKAGE_NAME. Inspects package records and relationships. Output: versions, reverse dependencies, and dependency-related data. Caveat: it is less immediately readable than show.

show — Syntax: apt-cache show PACKAGE_NAME. Displays readable package metadata. Output: descriptions, versions, architecture, maintainer, and dependencies. Caveat: multiple records can appear for multiple available versions.

stats — Syntax: apt-cache stats. Summarizes the metadata cache. Output: aggregate package, dependency, provides, and related counts. Caveat: it is not an installed-package count.

unmet — Syntax: apt-cache unmet. Reports unmet relationships represented in the cache. Output: diagnostic dependency information. Caveat: it does not repair package problems.

depends — Syntax: apt-cache depends PACKAGE_NAME. Displays package relationships. Output: Depends, Recommends, alternatives, virtual packages, and related labels. Caveat: not every listed relationship is mandatory.

rdepends — Syntax: apt-cache rdepends PACKAGE_NAME. Finds packages that reference a package. Output: reverse references. Caveat: references can be optional or negative relationships.

pkgnames — Syntax: apt-cache pkgnames [PREFIX]. Lists known package names. Output: names from local cache indexes. Caveat: output is not restricted to installed packages.

Choosing between apt-cache and apt

apt-cache remains useful and is commonly available on APT-based systems. Modern user-facing APT commands also provide equivalents for common queries, especially apt search and apt show:

apt search network mapper
apt show nmap

Use apt search or apt show for convenient interactive queries. Use apt-cache when inspecting the package cache, following existing documentation, using a familiar subcommand such as stats or unmet, or maintaining compatibility with scripts and procedures that already use apt-cache.

Neither tool replaces apt update. Query commands depend on the local indexes, so refresh those indexes when repository data may be outdated.

Practical investigation workflow

1. Refresh metadata: sudo apt update.

2. Search for a candidate: apt-cache search network mapper.

3. Read the candidate's descriptive metadata: apt-cache show nmap.

4. Inspect package records and versions when needed: apt-cache showpkg nmap.

5. Review requirements and optional relationships: apt-cache depends nmap.

6. Before replacing or removing a foundational package, check references: apt-cache rdepends PACKAGE_NAME.

7. Use the package-management command only after identifying the package and understanding the likely relationships.

Troubleshooting apt-cache results

No expected package appears in search results

• Run sudo apt update and inspect repository errors.

• Check whether the repository containing the package is configured in /etc/apt/sources.list or /etc/apt/sources.list.d/.

• Try broader or alternate search terms. The package name may not match the software's familiar name.

apt-cache shows no information for a package name

• The package may not be available from enabled repositories.

• The local cache may be stale or incomplete.

• The supplied name may not be an actual package name.

• Refresh indexes, search related terms, and check that repository configuration matches the distribution release.

pkgnames looks like an installed-package list

pkgnames lists names known to the cache, including packages that are merely available from repository indexes. To query installed packages instead, use an installed-package tool such as:

dpkg-query -W

Dependency output is confusing

• Identify the label for each entry before deciding whether it is mandatory.

• Distinguish Depends and PreDepends from Recommends and Suggests.

• Look for alternatives and virtual package names.

• Use apt-cache show PACKAGE_NAME for a more readable view of package metadata.

apt-cache unmet reports a problem that is not resolved

The command reports relationships represented in the cache; it does not diagnose every transaction issue. Refresh the indexes, review the exact APT or dpkg error, and use appropriate package-repair or dependency-resolution procedures for the actual failure.

Key points

• apt-cache queries locally cached APT package metadata.

• sudo apt update refreshes the repository indexes that supply that metadata.

• Use search to discover packages, show for readable metadata, and showpkg for package records and relationships.

• Use depends and rdepends to examine forward and reverse package relationships.

• Use stats to understand cache composition, not to count installed software.

• Use pkgnames to list names known to the cache, optionally by prefix.

• Interpret optional relationships, alternatives, conflicts, and virtual packages carefully.