Pinning is the black art of Debian and its derivative distributions. Using pinning, you can set your preferences for which package repository to use, either for all installations or upgrades, or for a specific set of packages. Officially, however, Debian discourages pinning, because it can prevent package upgrades or even corrupt an entire system if used carelessly.

Debian, as you may know, uses three main repositories [1]. These are Stable, Testing, and Unstable, also known by their release names, which are currently Jessie, Stretch, and Sid – all characters from the Toy Story movies. A new package enters Debian in Unstable, and, when it meets certain requirements, moves to Testing. When a general release is made, the package moves to Stable. Between releases, StableUpdates and Backports are used to help keep Stable up to date with borrowings from Testing. Debian derivatives like Ubuntu organize repositories by other criteria but are still likely to have some repositories that are more stable or otherwise preferred.

However, both Debian's and Debian derivatives' main repositories are divided into sections based on licensing. The main section contains free-licensed packages, including core system components. By contrast, contrib contains free-licensed packages that depend on proprietary applications, while non-free contains proprietary packages. Debian installs with only main enabled, although contrib and non-free can be enabled by editing /etc/apt/sources.list and then running apt-get update.

The reason Debian discourages pinning is that it disrupts the repository system's careful arrangement of repositories by package quality – which can be disastrous at times. For example, when systemd was in Unstable, installing the packages on an otherwise Stable system slowed performance and limited the available display resolutions. These problems persisted for months, with no solution except a complete reinstall. Such problems are especially likely to occur in the months before a general release, when developers are concentrating on perfecting the packages in Testing to prepare for their move into the new Stable repository and often neglecting Unstable. They are also far more likely with core components, such as Linux kernels or desktop environments that have numerous essential dependencies.

Using third-party repositories can sometimes cause similar problems. Similarly, pinning can add unfree packages to an otherwise free-licensed system.

All the same, pinning remains popular. Debian can take a long time between releases, and some users will always want the most up-to-date versions of applications. Moreover, once set up, pinning is more convenient than alternatives such as constantly commenting and uncommenting lines in /etc/apt/sources.list. Fortunately, by keeping informed about Debian development and taking a few precautions, pinning can be used with minimum risk – although some risk is likely to remain.

Getting Priorities Straight

Pinning sets priorities for packages in the repositories listed in files in /etc/apt, such as sources.list, or else those at a particular URL (Figure 1). If you want to borrow from a repository, you must first add it to the sources for the system and make sure that the entry is not commented out and then run apt-get update. Otherwise, pinning has no effect.

Figure 1: Pinning prioritizes the package sources listed in /etc/apt that are not commented out.

By default, Debian assigns all repositories and gives each of the main repositories section an equal weight of 500 (Figure 2), preferring none of them (see below). You can check the current priorities on a system by running apt-cache policy. To read the priority for a particular package, run apt-cache policy PACKAGE.

Figure 2: By default, Debian assigns all the main repositories an equal priority. Lesser repositories like Backports and Updates are given a lesser priority.

Changing priorities means creating a preference file. In the past, all priorities were listed in /etc/apt/preferences, with each priority setting in a stanza separated from the others by a line above and below. In the last few years, though, Debian and its derivatives have used individual files in the /etc/apt/preferences.d directory (Figure 3). These individual files often use a .pref extension, although any file in preferences.d is read in setting priorities.

Figure 3: The default content of /etc.apt/preferences.d in Linux Mint.

The structure for defining a preference can begin with an Explanation line for adding comments, although in practice this line is rarely used. More often, the structure consists of three lines. The first line, Package, lists the package affected. The first line accepts regular expressions, so an asterisk (*) sets the priority for an entire repository – something that can be dangerous to do – while /WORD/ applies to any package that contains the enclosed word.

For safety, you are better off specifying an entire package or set of packages. For example, if you want the latest packages for the solitaire game pysolfc, you might complete the first line with *pysolfc*. For a package with numerous dependencies, such as a desktop environment, you might have to choose the regular expressions carefully, although probably dependencies would drag in any other files not covered by them – something you definitely will want to check. The most common first line is:

Package: *

Pin, the second line, usually defines the package source by defining the archive (a=), version (v=), release name (n=), and/or section component (c=). A private repository can be defined with label (l=). These building blocks can be combined in a comma-separated list, so that the line

Pin: release a=unstable,c=main,v-8.6

would apply to the main section of Unstable in Debian's 8.6 release. Less commonly, origin URL refers to a mirror site, or origin " " to the local system. Refer to the sources.list file to check that you have identified a source properly.

The third line is Pin-Priority. Its working is simple: The package source with the highest number is used first. If it is not available for some reason, the package will be installed – if possible – from the source with the next highest possibility. Table 1 lists the effect of each priority. A sample third line would be:

Pin-Priority: 500

Priorities can be used in a number of ways beside the obvious. For example, problems with dependencies can sometimes be fixed by setting priorities to a number over a thousand, so that you can downgrade packages to what they once were. Similarly, a cautious administrator could set priorities so that the Stable has a priority of 1000, and everything else has a negative priority, so that even if a user with the right privileges adds another source, those sources will never be used in preference to Stable (Figure 4).

Figure 4: A preference file that gives high priority to all code-named repositories and a low priority to all other sources. By setting priorities in this way, the file favors high-quality sources.

However you set source priorities, you always need to be cautious, because dependencies can lead to unexpected results. You should also be aware that, if a source is unavailable for some line, the source with the next highest priority will be used, which can sometimes lead to a broken package. In my experience, the safest way to use pinning is to assign a priority to the fewest number of packages possible. If that requires more thought and more .pref files, it should also cause fewer problems.

Using Pinning

When you have set priorities, run apt-get update to enable them. Before adding or upgrading packages, you should check the descriptions of the packages involved. Take special note of their dependencies: Generally, the more dependencies a package has, or the more core components are among its dependencies, the more borrowing from Testing, Unstable, or third parties is likely to cause problems.

Another precaution to use with pinning is to run apt-get first with the -s or --simulate option. This option tells you what the result of your action will be but makes no changes to your system. The more complicated an action, the more sensible using this option becomes.

Pinning does not work automatically – only when you specify. It can be used with one of two command structures. The first example is:

apt-get install PACKAGE/unstable

Replace unstable with the repository that you wish to use.

With this command, apt-get installs the Unstable version of the package and tries to install the dependencies from Stable. This tactic does not always work, because some packages require a specific version of a dependency, but it will explain what the problem is. You will then need to fix the broken packages before you can install or upgrade anything else.

The second command structure example is:

apt-get -t unstable install PACKAGE

Again, replace Unstable with another repository if necessary.

With this structure, both the package and its dependencies are taken from Unstable. But whether this tactic works depends on how much effort the maintainer has put into the package. If they have only made sure that the package works for a specific set of circumstances, you are just as likely to have broken packages to fix as with the first tactic. No matter how you use pinning, some uncertainty always remains possible.

A Final Caution

If I sound overly cautious, the reason is that, like many Debian users, I have sometimes been tempted by one upgrade too many, condemning a system to dependency hell and hours of recovery.

Pinning can be a handy tool, which is why it remains popular. However, it is not a tool for beginners, nor one to use recklessly. After all, at this stage in Linux's development, having the latest upgrade matters less than it once did when the gaps in functionality were larger and more frequent.

Still, if you are like me, you will probably to be tempted to pin at some point. If so, then use it carefully, so that it helps rather handicaps you.