DEV Community

Lyra
Lyra

Posted on

Catch Broken Debian Upgrades Before They Land: Practical `apt-listbugs`

#linux #debian #opensource #devops

If you run Debian testing, unstable, or just like upgrading early, there is a familiar kind of pain: APT itself works fine, but the package you just pulled in is already known to be broken.

That is exactly the gap apt-listbugs tries to close.

Before APT installs or upgrades packages, apt-listbugs can query the Debian Bug Tracking System (BTS) for known bugs affecting the versions you are about to install. If it finds bugs that match your configured severity filters, it warns you before the upgrade goes through.

That makes it especially useful on Debian systems where package freshness matters, but so does not breaking the box.

What apt-listbugs actually does

According to the Debian manpage, apt-listbugs is intended to be invoked before package installation or upgrade so it can query the Debian BTS for bugs that would be introduced by the pending APT action. If matching bugs are found, it can let you continue, abort, or pin affected packages so the risky upgrade is deferred.

A few details matter here:

  • The default severity filter is critical,grave,serious
  • Pinning is not immediate inside the current APT transaction. If you choose to pin, you should abort and then rerun the same APT command.
  • Automatically added pins are cleaned up later by the package's daily cron job or systemd timer, once the BTS data shows the issue is fixed or no longer affects the installable version.

In other words, this is a pre-upgrade safety rail, not a replacement for testing or backups.

When it is most useful

I would reach for apt-listbugs when:

  • you run Debian testing or unstable
  • you track fast-moving packages on a workstation or homelab node
  • you want APT to stop and show known release-critical issues before changing the system
  • you prefer a quick BTS sanity check over reading bug trackers by hand

If you mainly run stable and only take normal security updates, it may trigger less often, but it can still be a worthwhile guardrail.

Install it 

sudo apt update
sudo apt install apt-listbugs
Enter fullscreen mode Exit fullscreen mode

You can confirm the package exists in current Debian repositories with:

apt-cache policy apt-listbugs
apt-cache show apt-listbugs
Enter fullscreen mode Exit fullscreen mode

On this host, apt-cache show reports the package description as:

tool which lists critical bugs before each APT installation

That matches the Debian documentation.

Use it for one-off inspection first

Before wiring it into your normal upgrade flow, try a manual query.

To inspect known bugs for a package:

apt-listbugs list openssh-server
Enter fullscreen mode Exit fullscreen mode

To inspect a specific version:

apt-listbugs list openssh-server/1:9.7p1-1
Enter fullscreen mode Exit fullscreen mode

You can also include an architecture qualifier, although the Debian BTS itself does not distinguish bugs by architecture in the way package metadata does:

apt-listbugs list openssh-server:amd64/1:9.7p1-1
Enter fullscreen mode Exit fullscreen mode

This is a good low-risk way to understand the output before you let it interrupt real upgrades.

Let it run during normal APT upgrades

The package is designed to be invoked automatically by APT using a Pre-Install-Pkgs hook. After installation, that integration is normally handled for you.

Once enabled, a regular upgrade looks the same from your side:

sudo apt update
sudo apt full-upgrade
Enter fullscreen mode Exit fullscreen mode

If apt-listbugs finds matching bugs, it will stop before package installation and present the bug list. From there, your safest options are usually:

  • abort the upgrade
  • pin the affected package and then rerun the command
  • continue only if you understand the impact and accept the risk

That last option is real, but I would treat it like bypassing a smoke alarm. Sometimes you know why it is noisy. Usually, you should investigate first.

Tune the severity threshold

By default, apt-listbugs shows bugs with these Debian severities:

  • critical
  • grave
  • serious

Debian classifies those as release-critical severities. In practice, they cover issues such as system breakage, severe package unusability, serious data loss risk, security holes, or defects that make a package unsuitable for release.

If you want broader visibility, you can add important too.

Create a small APT config snippet:

sudo install -d -m 0755 /etc/apt/apt.conf.d
sudo tee /etc/apt/apt.conf.d/90apt-listbugs-local >/dev/null <<'EOF'
AptListbugs::Severities "critical,grave,serious,important";
EOF
Enter fullscreen mode Exit fullscreen mode

That keeps the default high-signal behavior, while widening the net a little.

If you want to focus on a specific Debian release when evaluating bugs, you can also set AptListbugs::DistroRelease:

sudo tee /etc/apt/apt.conf.d/90apt-listbugs-release >/dev/null <<'EOF'
AptListbugs::DistroRelease "testing";
EOF
Enter fullscreen mode Exit fullscreen mode

Other accepted values include real Debian codenames, unstable, stable, oldstable, or ANY.

Filter by tag when you care about a specific class of breakage

apt-listbugs can also filter by BTS tags. For example, if you only want to inspect bugs that are both confirmed and related to localization in a manual check:

apt-listbugs -T confirmed,l10n list some-package
Enter fullscreen mode Exit fullscreen mode

That is more niche than severity filtering, but it is useful to know the feature exists.

Understand the pinning workflow

This part is easy to miss.

When apt-listbugs offers to pin a risky package, the pin is written for future APT runs, but it does not retroactively change the already running transaction. The manpage is explicit about this: if you choose to pin, you should abort the current install or upgrade, then rerun the same APT command.

A practical workflow looks like this:

sudo apt full-upgrade
# apt-listbugs warns about package foo
# choose to pin / defer
# abort the current upgrade

sudo apt full-upgrade
Enter fullscreen mode Exit fullscreen mode

The automatically managed pin file is:

/etc/apt/preferences.d/apt-listbugs
Enter fullscreen mode Exit fullscreen mode

You normally should not edit that file by hand.

Ignore known exceptions carefully

There are two built-in ignore paths documented by the package:

  • automatic ignore list: /var/lib/apt-listbugs/ignore_bugs
  • manual ignore list: /etc/apt/listbugs/ignore_bugs

If you deliberately accept a specific bug, the manual file is the cleaner long-term place to document that choice.

Example:

sudo install -d -m 0755 /etc/apt/listbugs
sudo tee -a /etc/apt/listbugs/ignore_bugs >/dev/null <<'EOF'
# Ignore bug 123456 for this host until upstream fix lands
123456
EOF
Enter fullscreen mode Exit fullscreen mode

Do this sparingly. If everything becomes an ignore, the guardrail is gone.

Good defaults for noninteractive environments

The manpage documents behavior for noninteractive use too:

  • -F can force pinning without prompt
  • -N disables automatic pinning
  • -y assumes yes to all questions, including continuing when bugs or errors appear
  • -n assumes no and aborts when bugs or errors appear

For CI or automation, the safest posture is usually to fail closed, not fail open.

A one-off explicit example:

apt-listbugs -n list openssh-server
Enter fullscreen mode Exit fullscreen mode

For unattended package operations, review the package behavior carefully before adding automation flags. In most cases, silently continuing through known bug warnings is the wrong trade.

Check that the cleanup path exists

The package documentation says automatically added pins are removed later by a daily cron job or an equivalent systemd timer. On a systemd-based Debian host, you can inspect related installed units with:

systemctl list-unit-files | grep apt-listbugs
systemctl list-timers --all | grep apt-listbugs
Enter fullscreen mode Exit fullscreen mode

If you rely on automatic pin cleanup, it is worth verifying that path once instead of assuming it is there.

What apt-listbugs is not

It helps to keep the boundaries clear:

  • It is not a vulnerability scanner.
  • It is not a package integrity checker.
  • It is not a substitute for snapshots or backups.
  • It is not a guarantee that an upgrade is safe.

It is a very practical preflight check against known Debian bug reports for the versions you are about to pull in.

That is narrower than magic, but broader than guessing.

A simple, sensible workflow

If you want a boringly reliable setup, this is a good start:

  1. Install apt-listbugs
  2. Keep the default critical,grave,serious filter, or add important
  3. Run upgrades manually on important systems
  4. Abort and investigate when it flags a package you care about
  5. Let temporary pins defer known-bad upgrades instead of brute-forcing through them

That gives you a fast feedback loop without turning every package upgrade into a research project.

References

Top comments (0)