apt_preferences (5)
NAME
apt_preferences - Preference control file for APT
DESCRIPTION
The APT preferences file /etc/apt/preferences can be used to control
which version of a package will be selected for installation.
Several versions of a package may be available for installation when
the sources.list(5) file contains references to more than one distribu-
tion (for example, stable and testing); furthermore, several instances
of the same version of a package may be available when the file con-
tains references to more than one download site for a particular dis-
tribution. APT assigns a "priority" to each instance that is avail-
able. (In what follows, an "instance" will be an instance of a package
that is available according to sources.list(5).) Subject to dependency
constraints, apt-get installs the instance with the highest priority.
If two instances have the same priority then it installs the more
recent one, that is, the one with the higher version number.
The APT preferences file overrides the priorities that APT assigns to
package instances by default, thus giving the user control over which
one is selected for installation.
APT'S DEFAULT PRIORITY ASSIGNMENTS
If there is no preferences file, or if there is no entry in the file
that applies to a particular instance, then the priority assigned to
that instance is the priority of the distribution to which that
instance belongs. It is possible to single out a distribution, called
the "target release", which receives a higher priority than other dis-
tributions. The target release can be set on the apt-get command line
or in the APT configuration file /etc/apt/apt.conf. For example,
# Command to install the testing version of some-package
apt-get install -t testing some-package
# Configuration setting to make stable the target release
APT::Default-Release "stable";
If a target release has been specified then APT uses the following
algorithm to set the priorities of the instances of a package. Assign:
priority 100
to the instance that is already installed (if any).
priority 500
to the instances that are not installed and do not belong to the
target release.
priority 990
to the instances that are not installed and belong to the target
release.
If no target release has been specified then APT simply assigns prior-
ity 100 to all installed package instances and priority 500 to all
uninstalled package instances.
· Install the highest priority instance.
· If two or more instances have the same priority, install the most
recent one.
· If two or more instances have the same version number, install the
one whose source is listed earliest in sources.list(5). (The
installed instance, if there is one, is always preferred in such a
comparison unless apt-get --reinstall is used.)
In a typical situation, the installed instance of a package (priority
100) is not as recent as one of the instances available from the
sources listed in the sources.list(5) file (priority 500 or 990). Then
the package will be upgraded with the command: apt-get install or apt-
get dist-upgrade.
Rarely, the installed instance of a package is more recent than any of
the other available instances. The package will not be downgraded.
Sometimes the installed instance of a package is more recent than the
version belonging to the target release, but not as recent as a version
belonging to some other distribution. Such a package will indeed be
upgraded, because at least one of the available instances has a higher
priority than the installed instance.
THE EFFECT OF APT PREFERENCES
The APT preferences file allows the system administrator to customize
priorities. The file consists of one or more multi-line records sepa-
rated by blank lines. Records can have one of two forms, a specific
form and a general form.
· The "specific" form pins a priority (a "Pin-Priority") to a specified
package and specified version or version range. For example, the
following record pins a high priority to all versions of the perl
package whose version number begins with "5.8".
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
· The "general" form pins a priority to all of the package versions in
a given distribution (that is, to all the versions of packages that
are listed in a certain Release file), or to all of the package
instances coming from a particular Internet site, as identified by
its fully qualified domain name.
This general-form entry in the APT preferences file applies only to
groups of packages. For example, the following record causes APT to
assign a high priority to all package instances available from the
local site.
Package: *
Pin: origin ""
Pin-Priority: 999
A note of caution: the keyword used here is "origin". This should
Package: *
Pin: release a=unstable
Pin-Priority: 50
The following record causes APT to assign a high priority to all
package versions belonging to any release whose "Archive" (a) name is
"stable" and whose release "Version" (v) number is "3.0".
Package: *
Pin: release a=unstable, v=3.0
Pin-Priority: 50
HOW APT INTERPRETS PRIORITIES
Priorities (P) assigned in the APT preferences file must be positive or
negative integers. They are interpreted as follows (roughly speaking):
P > 1000
causes an instance to be installed even if this constitutes a
downgrade of the package
990 < P <=1000
causes an instance to be installed even if it does not come from
the target release, unless the installed instance is more recent
500 < P <=990
causes an instance to be installed unless there is an instance
available belonging to the target release or the installed ver-
sion is more recent
100 < P <=500
causes an instance to be installed unless there is an instance
available belonging to some other distribution or the installed
version is more recent
0 <= P <=100
causes an instance to be installed only if there is no installed
instance of the package
P < 0 prevents the instance from being installed
If one of the specific-form records described above matches an avail-
able package instance, then that record determines the priority of the
instance. If two specific-form records match an available instance,
then the first record encountered determines the priority. If two gen-
eral-form records match an available instance, then the first record
encountered determines the priority.
For example, suppose the APT preferences file contains the three
records presented earlier:
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
Package: *
Pin: origin ""
Pin-Priority: 999
version is 5.9*, then perl will be downgraded.
· An instance of any package other than perl that is available from the
local system has priority over other instances, even instances
belonging to the target release.
· An instance of a package whose origin is not the local system but
some other site listed in sources.list(5), and which belongs to an
"unstable" distribution, is only installed if it is selected for
installation and no instance of the package is already installed.
DETERMINATION OF PACKAGE VERSION AND DISTRIBUTION PROPERTIES
The locations listed in a system's sources.list(5) file should provide
Packages and Release files to describe the package instances available
at that location.
The Packages file is normally found in the directory .../dists/dist-
name/component/arch: for example, .../dists/stable/main/binary-
i386/Packages. It consists of a series of multi-line records, one for
each package available in that directory. Only two lines in each
record are relevant for setting APT priorities:
the Package: line
gives the package name
the Version: line
gives the version number for the named package
The Release file is normally found in the directory .../dists/dist-
name: for example, .../dists/stable/Release, or
.../dists/woody/Release. It consists of a single multi-line record
which applies to all of the package instances in the directory tree
below its parent. Unlike the Packages file, nearly all of the lines in
a Release file are relevant for setting APT priorities:
the Archive: line
names the archive to which all the package instances in the
directory tree belong. For example, the line Archive: stable
specifies that all of the packages in the directory tree below
the parent of the Release file are in the stable archive. Spec-
ifying this value in the APT preferences file would require the
line:
Pin: release a=stable
the Version: line
names the release version. For example, the package instances
in the tree might belong to Debian GNU/Linux release version
3.0. There is normally no version number for the "testing" and
"unstable" distributions because they have not yet been
released. Specifying this in the APT preferences file would
require one of the following lines.
Pin: release v=3.0
Pin: release a=stable v=3.0
Pin: release 3.0
Pin: release c=main
the Origin: line
names the producer of the package instances in the directory
tree of the Release file. Most commonly, this is Debian. Spec-
ifying this origin in the APT preferences file would require the
line:
Pin: release o=Debian
the Label: line
seems redundant. Most commonly, this is Debian. Specifying
this label in the APT preferences file would require the line:
Pin: release l=Debian
All of the Packages and Release files retrieved from locations listed
in the sources.list(5) file are kept in the directory
/var/lib/apt/lists, or in the file named by the variable
Dir::State::Lists in the apt.conf file. For example, the file
debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release
contains the Release file retrieved from the site debian.lcs.mit.edu
for binary-i386 architecture files from the contrib component of the
unstable distribution.
OPTIONAL LINES IN AN APT PREFERENCES RECORD
Each record in the APT preferences file can optionally begin with one
or more lines beginning with the word Explanation:. This provides an
opportunity to comment on the record.
The Pin-Priority: line in each APT preferences record is optional. If
omitted, APT assigs a priority of 1 less than the last value specified
on a line beginning with Pin-Priority: release ....
EXAMPLES
TRACKING STABLE
The following APT preferences file will cause APT to assign a priority
higher than the default (500) to all package versions belonging to a
stable distribution and a prohibitively low priority to package ver-
sions belonging to other Debian distributions.
Package: *
Pin: release a=stable
Pin-Priority: 900
Explanation: Uninstall or do not install any Debian-originated
Explanation: instances other than those in the stable distro
Package: *
Pin: release o=Debian
Pin-Priority: -10
With a suitable sources.list(5) file and the above preferences file,
any of the following commands will cause APT to upgrade to the latest
stable version(s).
apt-get install package-name
apt-get upgrade
The following APT preferences file will cause APT to assign a high pri-
ority to package versions from the testing distribution, a lesser
priority to package versions from the unstable distribution, and a pro-
hibitively low priority to package versions from other Debian distribu-
tions.
Package: *
Pin: release a=testing
Pin-Priority: 900
Package: *
Pin: release a=unstable
Pin-Priority: 800
Package: *
Pin: release o=Debian
Pin-Priority: -10
With the above APT preferences file, any of the following commands will
cause APT to upgrade to the latest testing version(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the specified package
to the latest version from the unstable distribution. Thereafter, apt-
get dist-upgrade and the others will cause upgrade of the package to
the latest unstable version.
apt-get install package/unstable
SEE ALSO
apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)
BUGS
See the APT bug page <URL:http://bugs.debian.org/apt>. If you wish to
report a bug in APT, please see /usr/share/doc/debian/bug-reporting.txt
or the reportbug(1) command.
AUTHOR
APT was written by the APT team <apt@packages.debian.org>.
17 August 2003 apt_preferences(5)