Selective Backports on Debian: Pinning Without Breaking Stable

The stable-but-current dilemma

You run Debian stable because you value a system that boots every morning without surprises. Then a single package falls behind: the web server lacks a protocol feature, the database engine misses an extension, or a build tool is too old for your project. Debian Backports exists precisely for this gap, offering newer versions rebuilt against the libraries in the current stable release. The catch is that adding Backports as an ordinary repository can make APT prefer those newer versions automatically, pulling in a cascade of changes you never asked for.

The useful takeaway: keep Backports available, but make it invisible to routine upgrades by default. APT pinning lets you lower the priority of the entire Backports suite and raise it only for the packages you explicitly choose.

How APT priorities work

Every package version known to APT carries a priority. By default, packages from the standard stable archive receive a priority of 500, while the version currently installed gets 100. When multiple versions exist, APT usually selects the one with the highest priority, breaking ties by version number. Backports packages can therefore outrank stable simply because they are newer.

Preferences files in /etc/apt/preferences.d/ override these defaults. Each stanza matches packages with Package:, selects an archive with Pin:, and assigns a numeric Pin-Priority:. A priority of 100 tells APT “install this only if I ask for it explicitly, or if nothing else is available.” A priority of 900 tells APT “prefer this version over the stable archive for the matched packages.”

A two-layer pin for Backports

The safe pattern is two rules: one that suppresses the whole Backports suite, and one that promotes the specific packages you want. You need root privileges to create these files.

First, lower the default priority for everything in Backports. Create /etc/apt/preferences.d/99-backports-default:

Package: *
Pin: release a=<codename>-backports
Pin-Priority: 100

Replace <codename> with your current release name, such as bookworm or trixie. The wildcard * matches every package, so no Backports version becomes an automatic candidate.

Second, raise the priority for your chosen package. If you need a newer nginx, create /etc/apt/preferences.d/99-nginx-backports:

Package: nginx nginx-common
Pin: release a=<codename>-backports
Pin-Priority: 900

List related packages explicitly if they must move together. A priority of 900 is high enough to beat the stable archive, but it stays below the dangerous 1000 threshold, which would permit APT to install an older version over a newer one.

Verify before you apply

Pinning is easy to get subtly wrong, so check the effective policy before installing anything.

Refresh the package lists. Run this with sudo:

sudo apt-get update

Inspect the candidate and priorities for your target package. This command does not require root:

apt-cache policy nginx

Look for two things: the installed version, the candidate version, and the priority table showing 100 for the Backports archive and 900 for the pinned package. If the candidate still points to the stable version, your Pin: line does not match the archive.

Simulate the transaction to see dependency changes without touching the system:

sudo apt-get -s install nginx

Review the output carefully. If the simulation proposes removing packages or pulling unrelated dependencies from Backports, reconsider the pin. Also simulate a routine upgrade to confirm nothing else is being dragged in:

sudo apt-get -s upgrade

After you are satisfied and have applied the change for real, confirm the package cache is consistent:

sudo apt-get check

Trade-offs and limitations

Pinning is a maintenance commitment, not a one-time fix. The suite name in your pin is tied to a release codename. After a distribution upgrade, <codename>-backports may no longer exist, and the pin will silently stop matching. Revisit these files whenever you move to a new stable release.

Backports versions are normally newer than stable, but not guaranteed. If a Backports package is older than the one in stable, a priority of 900 can force an unexpected downgrade. Always compare versions with apt-cache policy before raising a priority.

Automated tools such as unattended-upgrades read the same priorities you do. A pin that changes the candidate can alter what those tools decide to install. Simulate an upgrade after changing preferences, and consider whether your automation should exclude the pinned package.

Finally, do not mix testing or unstable into a stable system with the same technique. Those suites are not rebuilt against stable libraries in the same controlled way, and application binary interface (ABI) changes can break the base system. Official Backports is the supported path for selective newer software.

Rolling back

Because these files change APT’s behavior, removing them restores the default candidate selection. Delete the pin file and refresh:

sudo rm /etc/apt/preferences.d/99-nginx-backports
sudo apt-get update

Then confirm with apt-cache policy nginx that the candidate has returned to the stable archive.