APT pinning is how a Debian desktop says no to surprise upgrades

You added one extra repository to a Debian desktop, ran an upgrade, and now you are wondering why APT wants to pull a newer library, a different desktop component, or a vendor build you did not mean to prefer. That is the moment APT pinning is for. Not after the upgrade has gone wrong. Before it.

APT does not treat every available package as equal. Debian’s apt_preferences(5) manual for bookworm, from apt 2.6.1, describes the preference files at `/etc/apt/preferences` and `/etc/apt/preferences.d/` as the mechanism that controls which versions are selected for installation. When more than one version is available, APT assigns each version a priority. Subject to dependency constraints, `apt-get` selects the version with the highest priority. If two versions have the same priority, the newer version wins.

That last sentence is why mixed repositories need attention. A Debian/KDE desktop can have stable, testing, backports, a local repository, and a vendor repository all visible at once. Without a clear policy, you may not notice which source is becoming the candidate for a package until the resolver has already built a plan around it.

Start with an audit, not an edit. This command reads APT’s current policy and package sources; it does not install or remove anything:

```sh apt-cache policy ```

For a concrete package, this command shows the installed version, the candidate version APT would currently choose, and the version table for `apt` itself:

```sh apt-cache policy apt ```

The apt-cache(8) manual says `policy` exists to help debug issues relating to the preferences file: with no arguments it prints source priorities, and with a package name it prints detailed priority selection for that package. That is the habit to build before adding a new `.list` or `.sources` file.

The source definition matters too. Debian’s sources.list(5) manual describes both the older one-line format and the deb822-style `.sources` format. The deb822 form uses stanzas such as `Types`, `URIs`, `Suites`, and `Components`; it can also use `Enabled: no` to disable a stanza. The same manual describes `Signed-By` as a way to require a repository to pass apt-secure verification with a particular keyring or key fingerprint rather than every trusted key APT knows. That is separate from pinning, but it belongs in the same audit: one control says which repository is trusted to sign metadata, the other says which version APT should prefer.

A simple defensive pin might keep unstable visible but unattractive:

```text Package: * Pin: release a=unstable Pin-Priority: 50 ```

The Debian manual gives this same pattern as a low-priority pin for packages whose archive name is unstable. With that in place, unstable packages are still visible for deliberate installs, but they do not quietly outrank the normal desktop path.

The priority numbers matter. With no target release, APT normally gives installed package versions priority 100 and uninstalled package versions priority 500, with special handling for archives marked `NotAutomatic`. With a target release, versions from the target release get priority 990 and non-target versions get 500. APT’s default priorities do not exceed 1000, and apt_preferences(5) says APT will not downgrade unless an available version has a priority greater than 1000. That makes `1001` a sharp tool, not a general safety setting.

Use high pins for narrow, understood cases. Do not use them to make a mixed system feel simple. The apt_preferences(5) page is blunt that wrong settings can lead to uninstallable packages or wrong upgrade decisions, and that packages from one release are not tested in older or newer releases, or together with packages from different releases.

Before accepting an upgrade, simulate it. This command asks APT to show the actions it would take for the current system state without changing packages:

```sh apt-get -s upgrade ```

The apt-get(8) manual describes `-s` as a no-action simulation. It also warns that simulations run by non-root users may not have read access to all APT configuration, which can distort the result. So treat simulation as a useful check, not as proof that the system is safe.

APT pinning is also not rollback. It does not restore a previous filesystem, rebuild a working boot entry, or undo a configuration migration. On a desktop, rollback belongs to backups, snapshots, and tested recovery. Pinning is the rail that keeps the resolver from choosing a surprising track in the first place.

For Shadowfetch Linux, our own Debian/KDE desktop, the public place I would check next is the Linux changelog, because APT defaults are part of the operating system contract, not a private trick. AI assistance was used in drafting this article under human editorial direction; the product interest is first-party and disclosed.

A good pin does not make a mixed Debian system clever. It makes your intent visible before the upgrade asks for trust.