Debian Apt Pinning Guide – Lock Package Versions Safely

Learn how to lock specific Debian packages to a desired version with apt pinning, keeping security updates intact. Step‑by‑step instructions, example config, and verification checks are included.

Desired Outcome

On a Debian stable system you sometimes need to keep a package at a specific version – for example, to maintain compatibility with a legacy application – while still receiving timely security updates from the official Debian security repository. Apt pinning lets you assign a priority to a package or repository so that the package manager prefers one version over another without blocking security patches.

Prerequisites

Debian stable (e.g., Bookworm 12) installed with the standard APT repositories enabled.
Root or sudo access to modify APT configuration files.
Basic knowledge of the package names you want to pin.

Focused Procedure

Identify the package and desired version. For illustration, we will lock the nginx package to version 1.18.0-0ubuntu1.
```
apt-cache policy nginx
# Shows available versions and their origins.
```
Create a pinning file. Debian reads pinning rules from /etc/apt/preferences.d/. Create a new file, e.g., /etc/apt/preferences.d/nginx-pin.
```
# /etc/apt/preferences.d/nginx-pin
Package: nginx
Pin: version 1.18.0-0ubuntu1
Pin-Priority: 1001
```
The Pin-Priority value of 1001 forces APT to select this exact version, even if newer versions are available. A value greater than 1000 guarantees preference over all other sources.
Ensure the security origin remains at default priority. Do not add any pinning rule that lowers the priority of the security origin. The default priority for the security repository is 1000, which is sufficient to receive all security updates.
Update the package lists. After adding the pin file, run:
```
sudo apt-get update
```

Verify the pinning rule. Check the effective policy for the package:

apt-cache policy nginx
# Look for the line "Pin-Priority: 1001" and the chosen version.

Test an upgrade simulation. Ensure that the pinned package is not scheduled for upgrade while other packages can be updated:
```
sudo apt-get -s upgrade
# The output should not list nginx as a candidate for upgrade.
```
Apply the upgrade. If the simulation looks correct, perform the real upgrade:
```
sudo apt-get upgrade
```
The pinned package remains at 1.18.0-0ubuntu1, while other packages, including security updates, are applied.

Expected Checks

After apt-get update, run apt-cache policy nginx and confirm the pin priority and selected version.
Run apt-get -s upgrade to ensure no unintended upgrades are queued.
After a real upgrade, inspect /var/log/apt/history.log to verify that nginx was not upgraded.

Recovery Options

Remove the pin file. If you want to revert to normal package selection, delete the file:
```
sudo rm /etc/apt/preferences.d/nginx-pin
sudo apt-get update
```
Use apt-mark hold as a quick alternative. This command prevents the package from being upgraded but does not affect dependencies:
```
sudo apt-mark hold nginx
# To unhold:
sudo apt-mark unhold nginx
```
Check for dependency conflicts. If a pinned version causes a dependency break, you may need to pin the required dependency to a compatible version or remove the pin entirely.

Limitations and Caution

Pinning the entire repository (e.g., Origin: Debian with a low priority) can block critical security updates. Always keep the security origin at least 1000.
Setting Pin-Priority below 0 will make APT refuse to install the package from that source entirely.
Pinned packages may become incompatible with newer libraries if the system is upgraded elsewhere; monitor dependency warnings during upgrades.

Practical Checklist

Verify the desired version is available in the repositories.
Create a pin file with a priority > 1000 for exact version locking.
Keep the security origin at default priority.
Run apt-get update and apt-cache policy to confirm.
Simulate upgrades with apt-get -s upgrade.
Perform the real upgrade and review /var/log/apt/history.log.

By following this guide, Debian users can confidently lock specific packages while preserving the integrity of security updates.

Selective Package Version Control on Debian Stable: A Practical Guide to Apt Pinning