apt-file-fast 1.0.0

Fast sharded-index replacement for apt-file search on Debian/Ubuntu.

apt-file-fast

A fast replacement for apt-file search on Debian/Ubuntu — with dramatically faster index creation.

apt-file-fast builds and maintains a local search index of the files provided by your installed packages. Updates are incremental: only the data for packages added, removed, or changed since the last run is rewritten, so refreshing after apt install / apt upgrade is orders of magnitude faster than apt-file update.

Requirements

• Debian or Ubuntu
• Python 3.10+
• ripgrep (apt install ripgrep)

Install

From PyPI (recommended)

uv tool install apt-file-fast

Or run it one-shot without installing:

uvx apt-file-fast --help

From source

git clone https://github.com/izumo-m/apt-file-fast.git
cd apt-file-fast
uv sync
uv run apt-file-fast --help

Usage

Build or refresh the index (run once, then after every apt install/apt upgrade):

apt-file-fast update

Search for a file across all installed packages:

apt-file-fast search ls
apt-file-fast search -i README            # case-insensitive
apt-file-fast search -x '^/usr/bin/py.*'  # regex

Search without building the index — scan /var/lib/dpkg/info/*.list directly. Useful right after install (no update needed) or when you want a result that always reflects current dpkg state:

apt-file-fast search --no-cache /bin/ls

Clear the cache:

apt-file-fast clean

Options

Option	Scope	Description
--cache-dir PATH	all commands	Override cache location
-i, --ignore-case	search	Case-insensitive match
-x, --regexp	search	Treat the query as a regex
--no-cache	search	Skip the index; grep dpkg state directly

Index settings (compression, shard size, etc.) live in manifest.json and are edited via config set rather than update flags — see below. Run apt-file-fast --help for the full list of options.

Configuration

Index settings are stored in the cache's manifest.json. View them or change individual fields without rebuilding the index:

apt-file-fast config show
apt-file-fast config set --compression zstd --compression-level 7
apt-file-fast config set --search-threads 4
apt-file-fast config set --target-shard-bytes 1M

config set only persists the fields you pass; everything else is left alone. A first-time update with no manifest auto-generates one with the built-in defaults, so config set is optional.

Compression

Shards are zstd-compressed by default — both compression and decompression are several times faster than gzip at comparable ratios for this kind of repetitive TSV data. Each shard's filename (shard-NNNN.tsv.zst / .tsv.gz / .tsv) reflects how it is encoded, so a single cache directory can legitimately hold a mix of formats during a migration — search transparently handles all three via rg -z.

Migrating after a config change

Changing compression, compression_level, or target_shard_bytes only affects shards written after the change. Existing shards are carried verbatim by update until the packages they hold are added, removed, or changed. To force every shard onto the new setting:

apt-file-fast config set --compression zstd
apt-file-fast clean && apt-file-fast update

config set prints a reminder to stderr when it detects that a cache-affecting field changed against an existing index.

License

MIT © 2026 Masanao Izumo

---

Contributors and maintainers: see docs/development.md for internals and the release process.