APT-FILE(1)

📦

version 3.3ubuntu2 · 4 versions

3.3ubuntu2 · ubuntu resolute, ubuntu stonking (latest)
3.2.2 · ubuntu jammy
3.3 · ubuntu noble
3.3 · debian bookworm, debian trixie

💖 APT-FILE(1) — the apt-file glow-up 💖

okay so this is the manual page for apt-file, which lives under User Contributed Perl Documentation and is giving extremely helpful bestie energy. It's the command-line interface for the APT package searching utility. Let's get into it 🫶

✨ NAME ✨

apt-file — APT package searching utility — command-line interface 🎀

🌸 SYNOPSIS 🌸

apt-file [options] search pattern

apt-file [options] show package

🦋 DESCRIPTION 🦋

apt-file is a command line tool for searching files in packages for the APT package management system. literally its whole thing 💅

Some actions are required to run the search:

find — Alias for search. same vibe, different name, no cap.
list — List the contents of a package. This action is very close to the dpkg -L command except the package does not need to be installed or fetched. iconic behaviour honestly. 👑

By default, the list action interprets its pattern as if --fixed-string was specified.

list-indices — List the known Content indices and their status in a human readable format. These indices can be searched via the -I option (when enabled and after fetching the indices). The output is subject to change without notice and is therefore unsuited for script usage / automation. 🚨

For a machine-readable formats (e.g. automation), please use apt-config dump (search for options starting with Acquire::IndexTargets) and apt-get indextargets for checking the cache (Look for entries with an Identifier field starting with Contents-).

Note that individual sources.list entries can override the global default. Please consult sources.list(5) for more information on advanced configuration of the sources.list files.

search — Search in which package a file is included. A list of all packages containing the pattern pattern is returned.

Since Contents files does not contain directories, the pattern must match (part of a) file name. 🗂️

By default, the search action interprets its pattern as if --substring-match was specified.

show — Alias for list. yes bestie, they're the same, it's giving twin energy. 💖
update — This action that just calls apt update or apt-get update (depending on whether a tty is available).

The only advantage using this over a regular apt update or apt-get update directly is for the case where you have configured an apt-file specific configuration (via the Dir::Etc::apt-file-main configuration option). In that case, said configuration will be included automatically. convenient ✨

💅 OPTIONS 💅

The following options are available:

-a, --architecture architecture[,...] — This option is useful if you search a package for a different architecture from the one installed on your system.

It can be a comma-separated list for searching on multiple architectures.

-c, --config-file APT config-file — Configuration File; Specify a configuration file to use. The program will read the default configuration file and then this configuration file. If configuration settings need to be set before the default configuration files are parsed specify a file with the APT_CONFIG environment variable. See apt.conf(5) for syntax information.

The configuration file will be read relative to when it appears on the command line and can overwrite options that appear before it.

Note that the config file will also be passed to all APT tools called by apt-file.

-D, --from-deb — Use contents of the given .deb archives(s) as patterns. Useful for searching for file conflicts with other packages. Implies -F.
-f, --from-file — Read patterns from the given file(s), one per line. Use - as filename for stdin. If no files are given, then the list will be read from stdin. This is much faster than invoking apt-file many times. ⚡
--filter-origins origin[,...] — Only search indices from the listed origins (e.g. "Debian").

This filter matches against the name listed in the Origin field from the Release file.

If set to '*', this filter will be disabled (mostly useful for overriding the setting in a configuration file)

Alias of the APT config option: apt-file::Search-Filter::Origin

--filter-suites suite[,...] — Only search indices from the listed suites or codenames (e.g. "unstable").

This filter matches against the name listed in the Codename and Suite fields from the Release file. This means that either "unstable" or "sid" will match Debian's unstable suite.

If set to '*', this filter will be disabled (mostly useful for overriding the setting in a configuration file)

Alias of the APT config option: apt-file::Search-Filter::Suite

-F, --fixed-string — Do not expand search pattern with generic characters at pattern's start and end.

This is default for show and list actions.

--index-names type[,...], -I type[,...] — Only search indexes of the given name(s). If set to the special value ALL (case-sensitive), then all apt-file indices are searched.

The name(s) must match one or more of the identifiers used in the APT configuration (minus leading "Contents-"). Example if the configuration has the following snippets:

 Acquire::IndexTargets::deb::Contents-deb { ... };
 Acquire::IndexTargets::deb-src::Contents-dsc { ... };
 Acquire::IndexTargets::deb::Contents-udeb { ... };
 Acquire::IndexTargets::deb::Contents-deb-legacy {
    # Explicitly named to "Contents-deb"
    Identifier "Contents-deb";
    ...;
 };

Then, apt-file will recognise "deb", "dsc" and "udeb" as index names.

This option defaults to the value of the "apt-file::Index-Names" apt config option (or "deb" if omitted).

-i, --ignore-case — Ignore case when searching for pattern. case-insensitive queen 💅
-l, --package-only — Only display package name; do not display file names.
--stream-results — This is a special-usage option useful for dealing with searches that produce a high number of matches (10 000+) or/and automated processing of results.

Disable deduplication logic and immediately emit a result when a match is found.

This can greatly reduce the memory requirements for apt-file when processing searches with many matches. It will also reduce the time until the first match is emitted, which can be useful if matches can be processed as they are discovered and the consumer can handle duplicated matches. 🏃♀️

-o, --option APT::Option=Value — Set a Configuration Option; This will set an arbitrary configuration option. The syntax is -o APT::Option=Value. -o and --option can be used multiple times to set different options.

This option can be used to overwrite other command line options (e.g. "-o apt-file::Search-Filter::Origin=Debian" is effectively the same as "--filter-origins Debian").

Note that the config options passed via this option will also be passed to all APT tools called by apt-file.

--substring-match — Match if the given search pattern is a substring of a path or package.

This is default for search and find actions.

-v, --verbose — Run apt-file in verbose/debug mode. 🐛
-x, --regexp — Treat pattern as a (perl) regular expression. See perlreref(1) for details. Without this option, pattern is treated as a literal string to search for.

Be advised that this option can be rather slow. If performance is an issue, consider giving apt-file non-regex pattern matching too much and pipe the output to perl -ne '/<pattern-here>/'. This enables apt-file to use more optimizations and leaves less work to the "slower" regex. 🐌

-h, --help — Display a short help screen. 🫶

🎀 CONFIGURATION FILES 🎀

The apt-file command relies on the APT configuration. Notably, the default configuration makes apt fetch Contents files by default during a call to apt update.

For information on how to configure APT to fetch more or fewer Contents files, please refer to /usr/share/doc/apt-file/README.md.gz. 📖

The following files are notably interesting:

/etc/apt/apt-file.conf — Note this path is actually configurable by changing the value of the APT configuration called "Dir::Etc::apt-file-main". The listed value is merely the default value of that option.

If this file is present, apt-file will read this file after all default APT configuration files. Any config file -c or option (-o) will be evaluated before this file (and can override options set in it).

The file will also be passed on to all APT tools called by apt-file.

/etc/apt/apt.conf.d/50apt-file.conf — Chooses which Contents files to download. Note that apt-file recognises only "Acquire" targets that starts with "Contents-".

🌈 Special configurations similar to apt-file 2 🌈

Here are some apt-file 2 related work flows and how to (almost) emulate them with apt-file 3. They are documented as a starting point for people, who are attached to these. 🥺

The emulation may not be perfect for you out of the box. Patches are welcome to keep the examples updated as long as the examples remain "trivial".

Only make apt-file update fetch Contents files

If you are accustomed to apt update not fetching Contents files, then you can run /usr/share/doc/apt-file/examples/apt-file-2-update.sh. This script will configure apt and apt-file accordingly after best effort.

Please read the resulting /etc/apt/apt-file.conf.

Creating/using "user" caches

Previous versions of apt-file had a "--cache" option, which could be used to denote a directory to store the Contents files. This can be emulated by doing:

  # Setup
  $ mkdir -p ~/.cache/apt-file ~/.config
  $ touch ~/.cache/apt-file/dpkg-status
  $ sed '/^Dir::State/ d; /^Dir::Cache/ d;' \
    /usr/share/doc/apt-file/examples/apt-file.conf \
    > ~/.config/apt-file.conf
  $ cat <<EOF >> ~/.config/apt-file.conf
Dir::State "$HOME/.cache/apt-file";
Dir::Cache "$HOME/.cache/apt-file";
Dir::State::status "$HOME/.cache/apt-file/dpkg-status";
EOF

  # Update the cache
  $ apt-file -c ~/.config/apt-file.conf update

  # Search using the cache
  $ apt-file -c ~/.config/apt-file.conf show apt-file

  # Removal of the cache + config
  $ rm -fr ~/.cache/apt-file ~/.config/apt-file.conf

(You will probably want to add an alias apt-file in your ~/.bashrc)

Please read the resulting ./apt-file-user-cache.conf.

💀 BUGS, QUIRKS 💀

ok so nothing's perfect bestie, and there are a few known issues aka "quirks" you're gonna wanna keep in your mental notes app. let's go one by one 🫶

The Contents files do not include a leading slash on paths. so like, /bin/ls is literally just listed as bin/ls in the Contents file. wild, i know. which means if you're hunting for something in a top-level directory, it's often better to just… omit the leading slash entirely. 💅

the search algorithm will try to work around that leading slash for you, but it's not gonna catch every single case, no cap. so as a workaround, try pulling the leading slash to the beginning of your regular expressions. for example, use this:

/(?:usr/bin/vim|sbin/lvm)

instead of this:

/usr/bin/vim|/sbin/lvm

see the difference? the slash moves out front and becomes the main character. 👑

When a new line has been added to the sources.list and apt update has not been run, apt-file does not print a warning message. yeah. it just… doesn't say anything. 🙈 like bestie, a heads-up would be nice?? but no. silence.
By default, apt-file assumes that Contents files do not include a descriptive header (you know, the thing explaining what the file is and how to interpret it). but some tools have generated them with such a header — for example old versions of Contents files for the Debian archive, or Contents files generated by reprepro prior to version 5.2.0. 😭

so if you're searching files like that, you're gonna want to set apt-file::Parser::Check-For-Description-Header to true (e.g. in /etc/apt/apt.conf.d/50apt-file.conf) so apt-file can properly filter out the headers and avoid false matches. ✨

and the reason this isn't the default? it costs a factor 2 in overhead, and most common Contents files don't even have the header anymore. so it's giving "not worth it for everyone." (see #881405 for more deets, iykyk).

Not all APT repositories have Contents files. notably, common install media (CDs etc.) may just omit them to conserve space. iconic of them honestly, but also rude. 💀

the default configuration by apt-file marks Contents files as optional, so it'll just silently fail to search in Contents files in repositories like that. no drama, no error, just vibes. 🌸

🚪 EXIT CODES 🚪

apt-file has these defined exit codes, and they're lowkey perfect for scripting purposes. here's the whole roster:

0 — apt-file returned successfully. and if the command was a search, there was at least one result. slay. 🎉
1 — apt-file completed a search successfully, but it had no results. it did everything right and still came up empty. we've all been there bestie. 😭
2 — an error occurred (including invalid/conflicting user options). oops. 💀
3 — apt-file could not complete the command because the cache was empty. so please make sure there are indices enabled in the APT config and run apt update to fetch them. 🫶
4 — apt-file could not complete the command because the cache does not have any files matching the restrictions. so either change the restrictions (e.g. --index-names) or configure apt to fetch the relevant files and run apt update. pick your fighter. 💅
255 — there was an internal errors / uncaught exception in apt-file. please file a bug against apt-file. like actually please, it's not you it's them. 🐛

any other exit code is reserved for future use. so don't be out here interpreting random numbers, ok? that's not the move. ✋

👀 SEE ALSO 👀

apt(1), apt-cache(8), apt.conf(5)
The APT users guide in /usr/share/doc/apt/
The example config in /usr/share/doc/apt-file/examples
The README at /usr/share/doc/apt-file/README.md.gz

and that's the whole page bestie!! 💖 this one was perl v5.40.1, dated 2026-01-05, and it's the APT-FILE(1) manual — go forth and search your Contents files like the main character you are. 🌈✨👑

📦 where this page comes from

ubuntu resolute: apt-file 3.3ubuntu2
ubuntu stonking: apt-file 3.3ubuntu2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms