Pinning sources in Debian
Proceed with Caution

© Lead Image © Viktoriya Sukhanova, 123RF.com
Debian discourages the use of pinning to set preferences for package repositories, because the practice can have disastrous results. We take a closer look.
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.

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
.

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.

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:
Table 1
Priority Settings
Setting | Effect |
---|---|
More than 1000 |
Version is installed even if it means downgrading the package version. Can be useful for fixing broken packages. |
990-1000 |
Version is installed even if not from the target release, unless the installed version is more recent. |
500-989 |
Version is installed unless the target release has a version or the installed version is most recent. This is the default priority for Debian. |
100-499 |
Version is installed unless another version exists in another repository or the installed version is more recent. |
0-99 |
Version is only installed if no other version is already installed. |
Less than 0 |
Prevents the version from being installed. Useful when you suspect a version may cause problems. |
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).

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.
Infos
- Debian repositories: http://www.datamation.com/open-source/when-to-use-which-debian-linux-repository.html
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
News
-
An All-Snap Version of Ubuntu is In The Works
Along with the standard deb version of the open-source operating system, Canonical will release an-all snap version.
-
Mageia 9 Beta 2 Ready for Testing
The latest beta of the popular Mageia distribution now includes the latest kernel and plenty of updated applications.
-
KDE Plasma 6 Looks to Bring Basic HDR Support
The KWin piece of KDE Plasma now has HDR support and color management geared for the 6.0 release.
-
Bodhi Linux 7.0 Beta Ready for Testing
The latest iteration of the Bohdi Linux distribution is now available for those who want to experience what's in store and for testing purposes.
-
Changes Coming to Ubuntu PPA Usage
The way you manage Personal Package Archives will be changing with the release of Ubuntu 23.10.
-
AlmaLinux 9.2 Now Available for Download
AlmaLinux has been released and provides a free alternative to upstream Red Hat Enterprise Linux.
-
An Immutable Version of Fedora Is Under Consideration
For anyone who's a fan of using immutable versions of Linux, the Fedora team is currently considering adding a new spin called Fedora Onyx.
-
New Release of Br OS Includes ChatGPT Integration
Br OS 23.04 is now available and is geared specifically toward web content creation.
-
Command-Line Only Peropesis 2.1 Available Now
The latest iteration of Peropesis has been released with plenty of updates and introduces new software development tools.
-
TUXEDO Computers Announces InfinityBook Pro 14
With the new generation of their popular InfinityBook Pro 14, TUXEDO upgrades its ultra-mobile, powerful business laptop with some impressive specs.