1
.\" This manpage has been automatically generated by docbook2man-spec
2
.\" from a DocBook document. docbook2man-spec can be found at:
3
.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/>
4
.\" Please send any bug reports, improvements, comments, patches,
5
.\" etc. to Steve Cheng <steve@ggi-project.org>.
6
.TH "APT_PREFERENCES" "5" "12 March 2001" "" ""
1
.\"Generated by db2man.xsl. Don't modify this, modify the source.
10
.de Sp \" Vertical space (when we can't use .PP)
16
.ie \\n(.$>=3 .ne \\$3
20
.TH "APT_PREFERENCES" 5 "29 February 2004" "Linux" ""
8
22
apt_preferences \- Preference control file for APT
11
The APT preferences file controls various aspects of the APT system.
12
It is meant to be user editable and manipulatable from software. The file
13
consists of a number of records formed like the dpkg status file, space
14
seperated sections of text with at the start of each line tags seperated
15
by a colon. It is stored in \fI/etc/apt/preferences\fR.
18
One purpose of the preferences file is to let the user select which version
19
of a package will be installed. This selection can be made in a number of
20
ways that fall into three categories, version, release and origin.
22
Selection by version can be done by exact match or prefix match. The format
23
is 2.1.2 or 2.2* for a prefix match. Matching by prefix
24
can be used to ignore the r in the Debian release versioning, like
25
2.1r* or to ignore Debian specific revisions, 1.1-*.
26
When matching versions with a prefix the highest matching version will
29
Selection by release is more complicated and has three forms. The primary
30
purpose of release selections is to identify a set of packages that match
31
a specific vendor, or release (ie Debian 2.1). The first two forms are
32
shortcuts intended for quick command line use. If the first character of the
33
specification is a digit then it is considered to be a release version match,
34
otherwise a release label match. Specifications which contain equals are
35
full release data matches and are a comma seperated list of one letter keys
36
followed by an equals then by the string. Examples:
40
v=2.1*,o=Debian,c=main
46
The data for these matches are taken from the \fIRelease\fR files
47
that APT downloads during an update. The available keys are:
50
This is the common name we give our archives, such as stable or
51
unstable. The special name now is used to designate
52
the set of packages that are currently installed.
55
Referes to the sub-component of the archive, main,
56
contrib etc. Component may be omitted if there are no
57
components for this archive.
60
This is a version string with the same properties as in the Packages file.
61
It represents the release level of the archive. Typical Debian release
62
numbers look like 2.1r2 with the r designating the release of
63
2.1. New releases are limited to security updates and other important
67
This specifies who is providing this archive. In the case of Debian the
68
string will read Debian. Other providers may use their own
74
This carries the encompassing name of the distribution. For Debian proper
75
this field reads Debian. For derived distributions it should
76
contain their proper name.
79
The final selection method is by origin. This is simply the site name
80
of the originating package files. The empty string is used for file URIs.
82
Version selection, particularly the latter two methods, are used in many
83
different parts of APT, not just the preferences file.
84
.SH "CANDIDATE VERSION POLICY"
86
Internally APT maintains a list of all available versions for all packages.
87
If you place multiple releases or vendors in your \fB\fIsources.list\fB\fR(5) file then
88
these features are available. By default APT selects the highest version
89
from all automatic sources. Some sources, such as
90
\fIproject/experimental\fR are marked Not Automatic - these fall
91
to the bottom of the selection pile.
93
When deciding what version to use APT assigns a priority to each available
94
version of the package. It then does two things, first it selects
95
the highest priorty version that is newer than the installed version of the
96
package, then it selects the highest priority version that is older than
97
the installed version. Next, if the older versions have a priority greater
98
than 1000 they are compared with the priority of the upgrade set, the larger
99
becomes the selected result. Otherwise the downgrade versions are ignored
100
and the highest priority of the ugprade set is selected.
102
It is possible to think of the priorities in strata:
105
Downgradable priorities
108
The downgrade prevention barrier
111
Standard priorities. 990 is the priority set by the
112
\fB--target-release \fR \fBapt-get\fR(8) option. 989 is the start for auto
113
priorities and 500 are all the default package files.
116
The currently installed version
119
Non automatic priorities. These are only used if the package
120
is not installed and there is no other version available.
123
The version is never selected.
126
Giving a pin a priority greater than 1000 will allow APT to downgrade
127
in order to get to that version.
129
Each package may be pinned to a specific version and each Packages file
130
has a priority for every package inside. The highest priority assigned
131
to a package is the one that is used.
133
A package pin looks like this:
142
The first line specifies the package, the second gives the Pin specification
143
and the last gives the priority of this pin. The first word of the pin
144
specification may be version, release or origin, the remainder of the field
145
is described in the Versioning section above.
147
A default pin is how the priorities of package files are set. Any number
148
of default pins may be specified, the first matching default will select
149
the priority of the package file. Only release or origin may be used in
150
the Pin specification since they match Packages files.
160
If the Pin-Priority field is omitted then the priority defaults to 989 for
162
.SS "INTERESTING EFFECTS"
164
Due to the downgrade prevention barrier at priority 1000 it is possible
165
that a lower priority version will be selected if the higher priority
166
would cause a downgrade. For instance, if package foo has versions
167
1.2, 1.1 and 1.0 installed, with
168
1.1 being the currently installed version and the priorities of
169
each version being 900, 100 and 950 repectively the winning version will be
172
In practice this is often desired. A user may use a default pin to
173
make the stable distribution the default and then use the
174
\fB--target-dist\fR option with \fBapt-get\fR(8) to select newer versions
175
from unstable. The packages that have been upgraded to unstable will
176
continue to follow the versions that are available in unstable since
177
the stable versions now fall below the downgrade prevention barrier.
179
If this is not desired then a default pin should be used to make unstable
180
have a priority less than 100.
182
Users of 3rd party add ons such as Helix GNOME can use this mechanism to
183
force the usage of Helix packages, or force the usage of Debian packages
184
by setting the priority of that source sufficiently high. It is even
185
possible to mass downgrade from one set of packages to another by
186
using a priority larger than 1000.
26
The APT preferences file \fI/etc/apt/preferences\fR can be used to control which versions of packages will be selected for installation\&.
29
Several versions of a package may be available for installation when the \fB\fIsources\&.list\fR\fR(5) file contains references to more than one distribution (for example, stable and testing)\&. APT assigns a priority to each version that is available\&. Subject to dependency constraints, \fBapt\-get\fR selects the version with the highest priority for installation\&. The APT preferences file overrides the priorities that APT assigns to package versions by default, thus giving the user control over which one is selected for installation\&.
32
Several instances of the same version of a package may be available when the \fB\fIsources\&.list\fR\fR(5) file contains references to more than one source\&. In this case \fBapt\-get\fR downloads the instance listed earliest in the \fB\fIsources\&.list\fR\fR(5) file\&. The APT preferences file does not affect the choice of instance, only the choice of version\&.
34
.SS "APT's Default Priority Assignments"
37
If there is no preferences file or if there is no entry in the file that applies to a particular version then the priority assigned to that version is the priority of the distribution to which that version belongs\&. It is possible to single out a distribution, "the target release", which receives a higher priority than other distributions do by default\&. The target release can be set on the \fBapt\-get\fR command line or in the APT configuration file \fI/etc/apt/apt\&.conf\fR\&. For example,
41
\fBapt\-get install \-t testing \fIsome\-package\fR\fR
48
APT::Default\-Release "stable";
54
If the target release has been specified then APT uses the following algorithm to set the priorities of the versions of a package\&. Assign:
58
to the version that is already installed (if any)\&.
62
to the versions that are not installed and do not belong to the target release\&.
66
to the versions that are not installed and belong to the target release\&.
70
If the target release has not been specified then APT simply assigns priority 100 to all installed package versions and priority 500 to all uninstalled package versions\&.
73
APT then applies the following rules, listed in order of precedence, to determine which version of a package to install\&.
77
Never downgrade unless the priority of an available version exceeds 1000\&. ("Downgrading" is installing a less recent version of a package in place of a more recent version\&. Note that none of APT's default priorities exceeds 1000; such high priorities can only be set in the preferences file\&. Note also that downgrading a package can be risky\&.)
80
Install the highest priority version\&.
83
If two or more versions have the same priority, install the most recent one (that is, the one with the higher version number)\&.
86
If two or more versions have the same priority and version number but either the packages differ in some of their metadata or the \-\-reinstall option is given, install the uninstalled one\&.
91
In a typical situation, the installed version of a package (priority 100) is not as recent as one of the versions available from the sources listed in the \fB\fIsources\&.list\fR\fR(5) file (priority 500 or 990)\&. Then the package will be upgraded when \fBapt\-get install \fIsome\-package\fR\fR or \fBapt\-get upgrade\fR is executed\&.
94
More rarely, the installed version of a package is more recent than any of the other available versions\&. The package will not be downgraded when \fBapt\-get install \fIsome\-package\fR\fR or \fBapt\-get upgrade\fR is executed\&.
97
Sometimes the installed version 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 when \fBapt\-get install \fIsome\-package\fR\fR or \fBapt\-get upgrade\fR is executed, because at least one of the available versions has a higher priority than the installed version\&.
99
.SS "The Effect of APT Preferences"
102
The APT preferences file allows the system administrator to control the assignment of priorities\&. The file consists of one or more multi\-line records separated by blank lines\&. Records can have one of two forms, a specific form and a general form\&.
106
The specific form assigns a priority (a "Pin\-Priority") to a specified package and specified version or version range\&. For example, the following record assigns a high priority to all versions of the \fIperl\fR package whose version number begins with "5\&.8"\&.
117
The general form assigns 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 \fIRelease\fR file) or to all of the package versions coming from a particular Internet site, as identified by the site's fully qualified domain name\&.
119
This general\-form entry in the APT preferences file applies only to groups of packages\&. For example, the following record assigns a high priority to all package versions available from the local site\&.
129
A note of caution: the keyword used here is "origin"\&. This should not be confused with the Origin of a distribution as specified in a \fIRelease\fR file\&. What follows the "Origin:" tag in a \fIRelease\fR file is not an Internet address but an author or vendor name, such as "Debian" or "Ximian"\&.
131
The following record assigns a low priority to all package versions belonging to any distribution whose Archive name is "unstable"\&.
137
Pin: release a=unstable
141
The following record assigns a high priority to all package versions belonging to any release whose Archive name is "stable" and whose release Version number is "3\&.0"\&.
146
Pin: release a=stable, v=3\&.0
153
.SS "How APT Interprets Priorities"
156
Priorities (P) assigned in the APT preferences file must be positive or negative integers\&. They are interpreted as follows (roughly speaking):
160
causes a version to be installed even if this constitutes a downgrade of the package
164
causes a version to be installed even if it does not come from the target release, unless the installed version is more recent
168
causes a version to be installed unless there is a version available belonging to the target release or the installed version is more recent
172
causes a version to be installed unless there is a version available belonging to some other distribution or the installed version is more recent
176
causes a version to be installed only if there is no installed version of the package
180
prevents the version from being installed
184
If any specific\-form records match an available package version then the first such record determines the priority of the package version\&. Failing that, if any general\-form records match an available package version then the first such record determines the priority of the package version\&.
187
For example, suppose the APT preferences file contains the three records presented earlier:
200
Pin: release unstable
210
The most recent available version of the perl package will be installed, so long as that version's version number begins with "5\&.8"\&. If any 5\&.8* version of perl is available and the installed version is 5\&.9*, then perl will be downgraded\&.
213
A version of any package other than perl that is available from the local system has priority over other versions, even versions belonging to the target release\&.
216
A version of a package whose origin is not the local system but some other site listed in \fB\fIsources\&.list\fR\fR(5) and which belongs to an unstable distribution is only installed if it is selected for installation and no version of the package is already installed\&.
220
.SS "Determination of Package Version and Distribution Properties"
223
The locations listed in the \fB\fIsources\&.list\fR\fR(5) file should provide \fIPackages\fR and \fIRelease\fR files to describe the packages available at that location\&.
226
The \fIPackages\fR file is normally found in the directory \fI\&.\&.\&./dists/\fIdist\-name\fR/\fIcomponent\fR/\fIarch\fR\fR: for example, \fI\&.\&.\&./dists/stable/main/binary\-i386/Packages\fR\&. 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:
230
gives the package name
234
gives the version number for the named package
238
The \fIRelease\fR file is normally found in the directory \fI\&.\&.\&./dists/\fIdist\-name\fR\fR: for example, \fI\&.\&.\&./dists/stable/Release\fR, or \fI\&.\&.\&./dists/woody/Release\fR\&. It consists of a single multi\-line record which applies to all of the packages in the directory tree below its parent\&. Unlike the \fIPackages\fR file, nearly all of the lines in a \fIRelease\fR file are relevant for setting APT priorities:
242
names the archive to which all the packages 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 \fIRelease\fR file are in a stable archive\&. Specifying this value in the APT preferences file would require the line:
246
Pin: release a=stable
252
names the release version\&. For example, the packages in the tree might belong to Debian GNU/Linux release version 3\&.0\&. Note that there is normally no version number for the testing and unstable distributions because they have not been released yet\&. Specifying this in the APT preferences file would require one of the following lines\&.
257
Pin: release a=stable, v=3\&.0
264
names the licensing component associated with the packages in the directory tree of the \fIRelease\fR file\&. For example, the line "Component: main" specifies that all the packages in the directory tree are from the main component, which entails that they are licensed under terms listed in the Debian Free Software Guidelines\&. Specifying this component in the APT preferences file would require the line:
274
names the originator of the packages in the directory tree of the \fIRelease\fR file\&. Most commonly, this is Debian\&. Specifying this origin in the APT preferences file would require the line:
278
Pin: release o=Debian
284
names the label of the packages in the directory tree of the \fIRelease\fR file\&. Most commonly, this is Debian\&. Specifying this label in the APT preferences file would require the line:
288
Pin: release l=Debian
294
All of the \fIPackages\fR and \fIRelease\fR files retrieved from locations listed in the \fB\fIsources\&.list\fR\fR(5) file are stored in the directory \fI/var/lib/apt/lists\fR, or in the file named by the variable Dir::State::Lists in the \fIapt\&.conf\fR file\&. For example, the file \fIdebian\&.lcs\&.mit\&.edu_debian_dists_unstable_contrib_binary\-i386_Release\fR contains the \fIRelease\fR file retrieved from the site debian\&.lcs\&.mit\&.edu for binary\-i386 architecture files from the contrib component of the unstable distribution\&.
296
.SS "Optional Lines in an APT Preferences Record"
299
Each record in the APT preferences file can optionally begin with one or more lines beginning with the word Explanation:\&. This provides a place for comments\&.
302
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 \&.\&.\&.\&.
306
.SS "Tracking Stable"
309
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 versions belonging to other Debian distributions\&.
313
Explanation: Uninstall or do not install any Debian\-originated
314
Explanation: package versions other than those in the stable distro
316
Pin: release a=stable
320
Pin: release o=Debian
327
With a suitable \fB\fIsources\&.list\fR\fR(5) file and the above preferences file, any of the following commands will cause APT to upgrade to the latest stable version(s)\&.
331
apt\-get install \fIpackage\-name\fR
333
apt\-get dist\-upgrade
339
The following command will cause APT to upgrade the specified package to the latest version from the testing distribution; the package will not be upgraded again unless this command is given again\&.
343
apt\-get install \fIpackage\fR/testing
348
.SS "Tracking Testing or Unstable"
351
The following APT preferences file will cause APT to assign a high priority to package versions from the testing distribution, a lower priority to package versions from the unstable distribution, and a prohibitively low priority to package versions from other Debian distributions\&.
356
Pin: release a=testing
360
Pin: release a=unstable
364
Pin: release o=Debian
371
With a suitable \fB\fIsources\&.list\fR\fR(5) file and the above preferences file, any of the following commands will cause APT to upgrade to the latest testing version(s)\&.
375
apt\-get install \fIpackage\-name\fR
377
apt\-get dist\-upgrade
383
The following command will cause APT to upgrade the specified package to the latest version from the unstable distribution\&. Thereafter, \fBapt\-get upgrade\fR will upgrade the package to the most recent testing version if that is more recent than the installed version, otherwise, to the most recent unstable version if that is more recent than the installed version\&.
387
apt\-get install \fIpackage\fR/unstable
189
\fBapt-cache\fR(8) \fB\fIapt.conf\fB\fR(5)
395
\fB\fBapt\-get\fR\fR(8) \fB\fBapt\-cache\fR\fR(8) \fB\fIapt\&.conf\fR\fR(5) \fB\fIsources\&.list\fR\fR(5)
192
See the APT bug page <URL:http://bugs.debian.org/apt>.
193
If you wish to report a bug in APT, please see
194
\fI/usr/share/doc/debian/bug-reporting.txt\fR or the \fBbug\fR(1) command.
197
APT was written by the APT team <apt@packages.debian.org>.
400
APT bug page: \fIhttp://bugs.debian.org/src:apt\fR\&. If you wish to report a bug in APT, please see \fI/usr/share/doc/debian/bug\-reporting\&.txt\fR or the \fB\fBreportbug\fR\fR(1) command\&.
added
removed
doc/apt_preferences.5
