Pinning and backports without breaking Debian

debian 13 / published / guide #39 / ≈ 4 min read

Debian is famously cautious — software is held back until it's proven stable. That's great for reliability, but every so often you need a newer version of one thing without upgrading the whole system. There are two clean ways to do that: backports (an official Debian repository of fresher packages) and pinning (a rule that says "prefer this version of that package from that source"). This guide explains both, slowly.

The golden rule: don't mix and match between Debian stable, testing, and unstable as a routine. That breaks systems. Backports + pinning gives you the same effect, cleanly.

Backports: the easy way

The Debian project maintains a special area called backports where volunteers backport newer versions of selected packages to the current stable release. Nothing in backports gets installed automatically — you ask for it.

Step 1: enable the backports repo

If you're on Trixie and used the new deb822 format (see apt sources the Trixie way), backports is already in your debian.sources if you added trixie-backports to Suites:.

If you're on the old format, edit /etc/apt/sources.list:

sudo nano /etc/apt/sources.list

Add this line:

deb http://deb.debian.org/debian trixie-backports main contrib non-free-firmware

Save, then:

sudo apt update

Step 2: install a single package from backports

sudo apt -t trixie-backports install kernel-the-newer-one

The -t flag (short for --target-release) means "for this command only, prefer the backports version." Without -t, the regular stable version is chosen even though backports is enabled.

Once installed, the backports version stays put. Future apt upgrade runs will update it from backports automatically (apt remembers where it came from).

What's in backports?

apt list --upgradable -a 2>/dev/null | grep trixie-backports
apt-cache policy linux-image-amd64

The second command shows every available version of a package and which repo each came from — useful for "is there a backport of this?"

Pinning: the precise way

Pinning is a config rule telling apt how to choose between competing versions of the same package. The classic use case: enable backports (or testing) for some packages but pin the rest at stable so apt never silently upgrades you across the boundary.

The default priorities

Without any pin file, apt assigns each repo a priority:

  • 500 — your current release (Trixie). Default.
  • 100 — backports. Available, but not chosen automatically.
  • 500 for testing/unstable if they're in your sources (this is why mixing without pins ruins systems — apt cheerfully upgrades everything).

If a package is available in multiple repos at the same priority, the highest version wins. To change this behaviour, write a pin file.

Pin files live here

Create one under /etc/apt/preferences.d/. The filename doesn't matter, just give it a clear name and skip the .list extension (use .pref or no extension):

sudo nano /etc/apt/preferences.d/99-pinning

Example 1: enable testing but only on demand

Imagine you've added trixie AND forky (the next testing release) to your sources. Without pinning, apt would happily upgrade you to forky. Pin to keep everything at trixie:

Package: *
Pin: release n=trixie
Pin-Priority: 990

Package: *
Pin: release n=forky
Pin-Priority: 100

Now stable wins by default. To install one package from testing:

sudo apt -t forky install some-package

Example 2: keep a package locked to a specific version

If a package update broke something and you're waiting for a fix:

Package: nginx
Pin: version 1.24.0-2
Pin-Priority: 1001

Priority >= 1000 means "even downgrade to reach this version." Priorities below 1000 won't downgrade.

Example 3: prefer the backports kernel always

Package: linux-image-* linux-headers-*
Pin: release n=trixie-backports
Pin-Priority: 990

Now apt picks the backports kernel by default.

Inspect what apt would do

apt-cache policy                 # current source priorities
apt-cache policy nginx           # which versions are available, which one wins
sudo apt install -s nginx        # simulate without changing anything

apt-cache policy is your best friend whenever you're unsure why apt picked a particular version.

The pattern, simplified

  • Need one newer package occasionally? Backports + apt -t.
  • Need a few packages tracked from a different release? Pin file, give that release priority 990 only for those package names.
  • Need to freeze a specific version because the new one is buggy? Pin to that version at priority 1001.

What NOT to do

  • Don't add testing or unstable to your sources without pinning — apt will start upgrading you across releases and you'll end up with a frankendebian.
  • Don't set APT::Default-Release in /etc/apt/apt.conf.d/ instead of pinning — older guides recommend this, but it's blunt and quietly skips packages that don't exist in the default release. A pin file is more predictable.
  • Don't leave pins for forgotten reasons. Add a comment to every pin file explaining what it's for and when it can be removed.

← back to index