Translation(s): English - Italiano - Español- Русский - 简体中文


This article tries to explain how to use APT Preferences. At this moment, only pinning is documented here.

Pinning

Before you consider 'pinning', you might want to check if the package you want has been backported to your release.

<!> When using apt-pinning, you must ensure compatibility of packages by yourself since Debian does not guarantee it. Note that apt-pinning is completely optional, and Debian does not encourage its use without thorough consideration.

Pinning allows you to run certain packages from one version (stable, testing, unstable) without the necessity of upgrading your entire system. However, pulling in packages from "later" distributions are prone to pull in libraries as well, which might have you end up with a system that has the disadvantages of stable (old software), the disadvantages of unstable/testing (security support not as good as stable, bugs) without the advantages of either.

At its most basic level, pinning involves two files, /etc/apt/sources.list and /etc/apt/preferences.

An additional role is played by the target release, which can be set in apt.conf (or in a /etc/apt/conf.d/... file and via the apt command line.

/etc/apt/sources.list

#### testing  #########
deb http://ftp.us.debian.org/debian testing main contrib non-free

#### unstable #########
deb http://ftp.us.debian.org/debian unstable main contrib non-free

In this example, we're pulling from testing and unstable. You could, of course, modify this to pull from stable as well.

/etc/apt/preferences

The 'preferences' file is where the actual pinning takes place. Here's an example:

Package: *
Pin: release a=testing
Pin-Priority: 900

Package: *
Pin: release a=unstable
Pin-Priority: 800

Package defaults to any, as specified by the asterisk. Pin specifies the release (testing and unstable). Pin-Priority specifies the priority level. 'apt-get' defaults to something along the lines of "highest package version wins". The above restructures this priority so that packages in testing are given a higher priority.

You should also refer to the apt_preferences(5) manpage.

Installing from unstable

Let's assume that we're running testing and we want to try enlightenment from unstable. There are basically two methods for installing:

 # apt-get install enlightenment/unstable
 # apt-get -t unstable install enlightenment

The first will not attempt to upgrade any packages on your system, so if specific dependencies are not met, the install will fail. The second method will attempt to install/upgrade any dependencies. Of course, given the above example, 'apt-get' will ask you before proceeding.

Notes from JoshuaRodman

Personally, I found the common configuration of a higher priority Testing pin and a lower priority Unstable pin to be problematic. At times, testing packages will depend upon other packages which are not currently in testing (perhaps representing a small glitch in testing) which causes packages to be automatically pulled in from unstable. In the period of testing prior to stabilization for the Woody release, this caused me to end up with over 100 unstable packages installed without even realizing it.

As a a result, I use a more conservative "only if I say so" approach to a mixed distribution, with a Pin file like this:

Package: *
Pin: release a=testing
Pin-Priority: 900

Package: *
Pin: release o=Debian
Pin-Priority: -10

Thus all debian packages are defaulted to priority -10, while testing receives a 900 point bonus. This invokes the behaviors:

From apt_preferences(5)

  500 < P <=990 :
        causes a version to be installed unless there is a version 
        available belonging to the target release or the installed 
        version is more recent
  [...]
  P < 0 :
        prevents the version from being installed

Note that a priority above 1000 will allow even downgrades no matter the version of the prioritary package. This means that you can use priority 1001 for a stable source if you want to downgrade to the stable versions of the packages you have installed (let's say from testing) on the system. this is not recommended unless the number of changes are minimal

Installing packages with apt-get install packagename/unstable and apt-get install -t unstable packagename will both still work, but unstable packages will only be installed by these commands.

Notes from ZugSchlus

Disclaimer

This page has been written by ZugSchlus, who not even remotely grasps the concept of pinning. So, please take the words "probably", "needs to be verified" and similiar wordings literally, and document your findings (may they be "this page is right" or "this page is wrong", optionally "this page is wrong because") here.

Description of Package Selection Process

-->Here is what one user thinks it should be.

ToDo: This needs to be verified

Examples of /etc/apt/preferences file

Example 1

Package: *
Pin: release o=Debian,a=testing
Pin-Priority: 900

Package: *
Pin: release o=Debian,a=unstable
Pin-Priority: 300

Package: *
Pin: release o=Debian
Pin-Priority: -1

Missing: Documentation what this preferences file does.

ZugSchlus tries to explain:

Problem: This pin behaves differently depending on which target release is set in other parts of apt configuration. Hence, this example cannot really be documented without adding more information. A non-pinned package being part of the target release has default priority 990, while other non-pinned packages have a default priority of 500.

Example 2

Objective: On an unstable system, pull dpatch from experimental.

A possible (and not completely correct) solution:

Example 3

From Mihamina rakotomandimby

Suppose you have a personnal repository where you have a personnal version of Postfix. You want Apt to prefer you version over official ones.

You may set preferences by Origin

Package: *
Pin: origin www.rktmb.org
Pin-Priority: 610

Package: *
Pin: origin ftp.fr.debian.org
Pin-Priority: 600

Debugging

apt-cache policy package gives information about the selection process. Unfortunately, it is not widely known what the output means. The following is a try to interpret:

 $ apt-cache policy exim4-daemon-light
 exim4-daemon-light
  Installed: 4.50-1
  Candidate: 4.50-1
  Package Pin: (not found)
  Version Table:
      4.50-4 555
        500 http://mirror sid/main Packages
  *** 4.50-1 555
        100 /var/lib/dpkg/status
      4.44-2 555
        500 http://mirror sarge/main Packages

The priority of each version/location is the number at the left of it. In this case, 500, 100, and 500. The number on the right of the version number displays the actual pin priority being placed on the package.

Notes from Ryan B.

If you're wondering what the options are for release file preferences, based on this link: http://www.debian.org/doc/manuals/repository-howto/repository-howto

we find:

Archive: archive

Component: component

Origin: Your Company

Label: Your Company Debian repository

Architecture: architecture

Thus, the line: "Pin: release a=testing" would find archive values in the release file named "testing".

Notes from GeorgiosZarkadas

I found that using a higher than 500 value to pin testing/unstable resulted in apt-get upgrade wanting to upgrade all packages with a newer version to testing/unstable even while I had stable pinned with a higher value than testing/unstable.

After, querying the outcome of apt-cache policy <some-package> for a number of the packages that apt-get upgrade considered that they should be upgraded, I concluded that if there are multiple versions with candidates pinned to 500 or higher, then pinning is considered after the version number. Thus the highest version with the highest pin weight among the candidates of that (and only that) version is selected.

For example (having stable pinned to 700, testing to 650 and unstable to 600):

root@freedom:/etc/apt# apt-cache policy deborphan
deborphan:
  Εγκατεστημένα: 1.7.28.3+squeeze1
  Υποψήφιο:      1.7.28.5
  Πίνακας Έκδοσης:
     1.7.28.5 0
        650 http://ftp.gr.debian.org/debian/ wheezy/main amd64 Packages
        600 http://ftp.gr.debian.org/debian/ sid/main amd64 Packages
 *** 1.7.28.3+squeeze1 0
        500 http://ftp.gr.debian.org/debian/ squeeze-proposed-updates/main amd64 Packages
        100 /var/lib/dpkg/status
     1.7.28.3 0
        500 cdrom://[Debian GNU/Linux 6.0.1a _Squeeze_ - Official amd64 DVD Binary-1 20110322-16:05]/ squeeze/main amd64 Packages
        700 http://ftp.gr.debian.org/debian/ squeeze/main amd64 Packages

Since my aim for using multiple sources and pinning was to be able to occasionally install a package from testing or unstable and not upgrade all my packages, pinning testing / unstable to values equal or greater than 500 is clearly an insuitable method for the stated cause.

However, I found that using a value less than 500 for testing/unstable has the desired effect. For example (removed stable pin and set testing to 450 and unstable to 400):

root@freedom:/etc/apt# apt-cache policy deborphan
deborphan:
  Εγκατεστημένα: 1.7.28.3+squeeze1
  Υποψήφιο:      1.7.28.3+squeeze1
  Πίνακας Έκδοσης:
     1.7.28.5 0
        450 http://ftp.gr.debian.org/debian/ wheezy/main amd64 Packages
        400 http://ftp.gr.debian.org/debian/ sid/main amd64 Packages
 *** 1.7.28.3+squeeze1 0
        500 http://ftp.gr.debian.org/debian/ squeeze-proposed-updates/main amd64 Packages
        100 /var/lib/dpkg/status
     1.7.28.3 0
        500 cdrom://[Debian GNU/Linux 6.0.1a _Squeeze_ - Official amd64 DVD Binary-1 20110322-16:05]/ squeeze/main amd64 Packages
        500 http://ftp.gr.debian.org/debian/ squeeze/main amd64 Packages

Notes from Dmitriy Matrosov

I think, that Georgios Zarkadas's conclusion (from previous notes) about "pinning considered by apt after version number":

I concluded that if there are multiple versions with candidates pinned to 500 or higher, then pinning is considered '''after''' the version number.

is wrong. Let's look once again at example he posted:

root@freedom:/etc/apt# apt-cache policy deborphan
deborphan:
  Εγκατεστημένα: 1.7.28.3+squeeze1
  Υποψήφιο:      1.7.28.5
  Πίνακας Έκδοσης:
     1.7.28.5 0
        650 http://ftp.gr.debian.org/debian/ wheezy/main amd64 Packages
        600 http://ftp.gr.debian.org/debian/ sid/main amd64 Packages
 *** 1.7.28.3+squeeze1 0
        500 http://ftp.gr.debian.org/debian/ squeeze-proposed-updates/main amd64 Packages
        100 /var/lib/dpkg/status
     1.7.28.3 0
        500 cdrom://[Debian GNU/Linux 6.0.1a _Squeeze_ - Official amd64 DVD Binary-1 20110322-16:05]/ squeeze/main amd64 Packages
        700 http://ftp.gr.debian.org/debian/ squeeze/main amd64 Packages

First, apt tries to upgrade from stable (squeeze/main) since stable has highest priority (700), but it sees, that installed package is newer:

sgf@shilvana:~$ dpkg --compare-versions 1.7.28.3 lt '1.7.28.3+squeeze1' ; echo $?
0

and priority 700 is not enough to downgrade. So, it looks further for candidate version. And now apt tries to upgrade from testing (wheezy/main) and sees, that version from testing is newer:

sgf@shilvana:~$ dpkg --compare-versions '1.7.28.3+squeeze1' lt 1.7.28.5 ; echo $?
0

And hence, this version (from testing) become a candidate.

So, in order to upgrade from stable (as Georgios Zarkadas wants), he must have this package at version <= than one found in stable.

References