APT pinning gives fine-grained control over which repository/version APT prefers for specific packages — useful when mixing sources (like Backports) or preventing specific packages from being upgraded past a certain version.
Why Pinning Matters
Without pinning, APT resolves version conflicts using default priority rules that might not match your actual intent — especially relevant once you've added additional repositories (Backports, third-party sources) alongside the standard Debian repositories.
Understanding APT Priority Numbers
| Priority | Effect |
|---|---|
| 1000+ | Install even if it's a downgrade from currently installed version |
| 990 | Default priority for the current/target release |
| 500 | Default priority for other available sources |
| 100 | Default priority for Backports |
| Below 0 | Never install this version |
Creating a Pin Configuration
sudo nano /etc/apt/preferences.d/backportsPackage: *
Pin: release a=bookworm-backports
Pin-Priority: 100This matches the default backports priority — explains why you need -t bookworm-backports to explicitly opt into backported packages rather than them being installed automatically.
Pinning a Specific Package to a Higher Priority
Package: nginx
Pin: release a=bookworm-backports
Pin-Priority: 500Raises priority specifically for Nginx from backports, making APT prefer the backported version for this package automatically without needing -t each time, while other packages remain unaffected.
Pinning a Package to Prevent Upgrades
Package: critical-app
Pin: version 2.5.1-1
Pin-Priority: 1001Locks a specific package at an exact version, preventing any upgrade even during a general apt upgrade — useful if a newer version has a known compatibility issue with your specific setup.
Checking Current Pin Priorities
apt-cache policy PACKAGE_NAMEShows the effective priority for each available version, helping you verify your pinning configuration is actually working as intended.
An Alternative to Pinning: apt-mark hold
sudo apt-mark hold PACKAGE_NAMEA simpler mechanism for the common case of just preventing a specific package from upgrading at all — see How to Use apt/dpkg Effectively: Package Management Deep Dive; use full pinning when you need more nuanced priority control across sources, not just a simple hold.
Common Pinning Mistakes
- Setting priorities too high broadly, causing unexpected automatic upgrades to less-tested repository versions
- Forgetting a pin exists, leading to confusion later about why a specific package isn't updating as expected
- Overly complex pinning configurations that become difficult to reason about over time
Common Errors
Pin doesn't seem to take effect — verify the pin file syntax is correct and run apt-cache policy to confirm the actual effective priority, since a syntax error in the pin file can cause it to be silently ignored.
Continue Reading
- How to Set Up Debian Backports for Newer Software Versions
- How to Use apt/dpkg Effectively: Package Management Deep Dive
- How to Manage Debian's APT Sources and Repositories
Browse more articles in Debian VPS Tutorials.
