Use Debian APT pinning to install one newer package while staying on stable

The problem and the useful answer

You need a newer version of a single package that exists in Debian unstable but not in your current stable release. Adding unstable to /etc/apt/sources.list and running a full upgrade is risky: APT may pull unstable versions of libraries and other dependencies, which can destabilize the whole system.

The useful answer is APT pinning. By creating files under /etc/apt/preferences.d/, you can tell APT to treat unstable as a low-priority source for everything except the specific packages you choose. The rest of the system stays on stable, while the targeted package can be installed or updated from unstable.

How APT pinning selects versions

APT assigns each available package version a priority. The candidate version is the version APT intends to install. Normally, the highest-priority repository wins. A pin overrides that default by assigning a custom Pin-Priority to packages matching a Pin rule, such as a release name.

Three fields matter most:

• Package: — which packages the rule applies to. Use * for all packages.
• Pin: — what to match, for example release a=unstable for the unstable archive.
• Pin-Priority: — the weight. Higher values are preferred. A priority of 50 means "only use this source if explicitly requested." A priority of 900 means "prefer this version unless a higher-priority rule applies."

APT reads preference files in lexical order, but priority values—not file order—determine the winner when multiple rules match.

Worked configuration: install ripgrep from unstable on Debian 12 stable

This example assumes Debian 12 (bookworm) as the base system and uses ripgrep as the target package. Substitute your own package name where shown.

Run the following as root or with sudo on the Debian host.

# 1. Add the unstable repository source
sudo tee /etc/apt/sources.list.d/unstable.list >/dev/null <<'EOF'
deb http://deb.debian.org/debian unstable main
EOF

# 2. Make unstable low priority for all packages
sudo tee /etc/apt/preferences.d/unstable-low.pref >/dev/null <<'EOF'
Package: *
Pin: release a=unstable
Pin-Priority: 50
EOF

# 3. Raise priority for the target package only
sudo tee /etc/apt/preferences.d/ripgrep-unstable.pref >/dev/null <<'EOF'
Package: ripgrep
Pin: release a=unstable
Pin-Priority: 900
EOF

# 4. Refresh package indexes
sudo apt-get update

Risk: adding unstable introduces packages that are not covered by the stable security team. The low priority of 50 prevents accidental upgrades, but explicitly installing a package from unstable can still pull unstable dependencies if the package requires newer libraries than stable provides.

Verify before installing

Run apt-cache policy to inspect candidate versions and priorities:

apt-cache policy ripgrep

Expected check: the output should list a stable entry (typically priority 500) and an unstable entry with priority 900. The line beginning with *** shows the candidate version APT will install. If the candidate is still the stable version, the pin is not taking effect.

Preview the installation with a simulation:

apt-get -s install ripgrep

Expected check: the simulation should show ripgrep being installed from unstable without upgrading unrelated stable packages to unstable. If the simulation proposes many new unstable packages or removes stable ones, stop and review the pins before proceeding.

To install:

sudo apt-get install ripgrep/unstable

After installation, check /var/log/apt/term.log to confirm the installed version came from unstable.

Limits and common mistakes

• Confusing Pin: with Pin-Priority:. Pin: selects the packages or repositories to match; Pin-Priority: sets the weight. A rule with Pin: but no Pin-Priority: does not create a usable override.
• Using overly aggressive priorities. A priority of 1000 or higher can force downgrades and break dependency resolution. A priority below 1 effectively blocks installation from that source unless you force it.
• Forgetting apt-get update. Preference changes do not refresh package metadata. Without updating indexes, apt-cache policy shows stale versions and the pin appears to fail.
• Pinning essential libraries. Pinning packages such as libc6 from unstable can force a partial system transition and leave the system in an inconsistent state. Limit pins to leaf applications where possible.
• apt-get full-upgrade can still change the package set. Pinning influences version selection, but a full-upgrade may install or remove packages to satisfy dependencies. Review its simulation output before running it on a pinned system.

Reverting the change

Editing preferences changes system state. To undo:

1. Remove the preference and source files:

sudo rm /etc/apt/preferences.d/ripgrep-unstable.pref
sudo rm /etc/apt/sources.list.d/unstable.list
sudo apt-get update

1. Return the package to stable:

sudo apt-get install ripgrep/stable

Risk: downgrading may remove packages that depended on the newer unstable version. Review the proposed changes before confirming.

Version assumptions

This behavior is consistent across Debian 10, 11, and 12 for standard APT versions. Newer dpkg or APT releases can change matching details, so always confirm with apt-cache policy after modifying preferences.