Using APT Pinning to Control Package Versions in Debian

In Debian, a standard apt upgrade installs the newest version available from enabled repositories. When a particular software version must stay fixed—for compatibility, or when mixing a testing repository into a stable system—you need a way to tell APT which version to prefer. APT pinning provides that control by assigning priority values to packages or repositories via preference files.

Desired Outcome

After completing this guide, a specific package will remain at a chosen version (or a repository will be used only when explicitly requested) despite newer versions being present in the package lists.

Prerequisites

• A Debian‑based system (Debian 11 Bullseye or 12 Bookworm recommended).
• Root access or sudo privileges to edit files in /etc/apt/.
• The exact package name and, if locking a version, the version string you want to keep (e.g., nginx version 1.18.0-6+deb11u).

Procedure

1. Create a preference file

Preference files are read from /etc/apt/preferences and any file under /etc/apt/preferences.d/. Using a dedicated file makes later removal easier.

# Run as root or with sudo
sudo editor /etc/apt/preferences.d/lock-nginx

Insert the following content to lock nginx to a specific version:

Package: nginx
Pin: version 1.18.0-6+deb11u
Pin-Priority: 1001

Explanation:

• Package: selects the target; use * for all packages.
• Pin: can be a version, an origin, or a release. Here we pin the exact version string.
• Pin-Priority: values >1000 allow APT to downgrade to this version if a newer one is installed.

2. Prioritize a repository (mixed stable/testing)

To keep the base system stable while allowing occasional installation of a tool from Debian Testing, lower the priority of the testing repository.

Package: *
Pin: release=testing
Pin-Priority: 90

With this pin, APT will only install packages from testing when they are not available in stable, or when you explicitly run apt install -t testing <package>.

3. Apply the configuration

The pins take effect the next time the package lists are refreshed.

sudo apt update

Verification

Check that APT sees the intended priority.

apt-cache policy nginx

Look for the line showing the pinned version with a priority of 1001 (or the repository priority you set). The “Candidate” version should match the pinned version.

Perform a dry‑run upgrade to confirm the package is not changed:

sudo apt-get upgrade -s nginx

The simulation should report that nginx is held back or kept at the current version.

Optionally, review the terminal log for unexpected changes:

grep nginx /var/log/apt/term.log

Risks and Limitations

• Dependency conflicts: Pinning a package to an old version may break if its dependencies are upgraded elsewhere.
• Security gaps: A locked version will not receive automatic security patches; monitor advisories for the pinned package.
• Total blockage: Setting Pin-Priority: -1 prevents installation altogether, which can affect other packages that depend on it.

Rollback Procedure

To restore default APT behavior, remove the preference file and refresh the package list.

1. Delete the file you created:

2. sudo rm /etc/apt/preferences.d/lock-nginx
   

3. Update the package list so the pin is no longer read:

4. sudo apt update
   

After removal, apt-cache policy <package> will show the default priorities and the candidate version will be the newest available from enabled repositories.