1
<?xml version="1.0" encoding="utf-8" standalone="no"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
5
<!ENTITY % aptent SYSTEM "apt.ent">
16
<!-- The last update date -->
17
<date>29 February 2004</date>
21
<refentrytitle>apt_preferences</refentrytitle>
22
<manvolnum>5</manvolnum>
25
<!-- Man page title -->
27
<refname>apt_preferences</refname>
28
<refpurpose>Preference control file for APT</refpurpose>
32
<title>Description</title>
33
<para>The APT preferences file <filename>/etc/apt/preferences</filename>
34
can be used to control which versions of packages will be selected
35
for installation.</para>
37
<para>Several versions of a package may be available for installation when
38
the &sources-list; file contains references to more than one distribution
39
(for example, <literal>stable</literal> and <literal>testing</literal>).
40
APT assigns a priority to each version that is available.
41
Subject to dependency constraints, <command>apt-get</command> selects the
42
version with the highest priority for installation.
43
The APT preferences file overrides the priorities that APT assigns to
44
package versions by default, thus giving the user control over which
45
one is selected for installation.</para>
47
<para>Several instances of the same version of a package may be available when
48
the &sources-list; file contains references to more than one source.
49
In this case <command>apt-get</command> downloads the instance listed
50
earliest in the &sources-list; file.
51
The APT preferences file does not affect the choice of instance, only
52
the choice of version.</para>
54
<refsect2><title>APT's Default Priority Assignments</title>
56
<para>If there is no preferences file or if there is no entry in the file
57
that applies to a particular version then the priority assigned to that
58
version is the priority of the distribution to which that version
59
belongs. It is possible to single out a distribution, "the target release",
60
which receives a higher priority than other distributions do by default.
61
The target release can be set on the <command>apt-get</command> command
62
line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>.
66
<command>apt-get install -t testing <replaceable>some-package</replaceable></command>
69
APT::Default-Release "stable";
73
<para>If the target release has been specified then APT uses the following
74
algorithm to set the priorities of the versions of a package. Assign:
78
<term>priority 100</term>
79
<listitem><simpara>to the version that is already installed (if any).</simpara></listitem>
83
<term>priority 500</term>
84
<listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem>
88
<term>priority 990</term>
89
<listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
94
<para>If the target release has not been specified then APT simply assigns
95
priority 100 to all installed package versions and priority 500 to all
96
uninstalled package versions.</para>
98
<para>APT then applies the following rules, listed in order of precedence,
99
to determine which version of a package to install.
101
<listitem><simpara>Never downgrade unless the priority of an available
102
version exceeds 1000. ("Downgrading" is installing a less recent version
103
of a package in place of a more recent version. Note that none of APT's
104
default priorities exceeds 1000; such high priorities can only be set in
105
the preferences file. Note also that downgrading a package
106
can be risky.)</simpara></listitem>
107
<listitem><simpara>Install the highest priority version.</simpara></listitem>
108
<listitem><simpara>If two or more versions have the same priority,
109
install the most recent one (that is, the one with the higher version
110
number).</simpara></listitem>
111
<listitem><simpara>If two or more versions have the same priority and
112
version number but either the packages differ in some of their metadata or the
113
<literal>--reinstall</literal> option is given, install the uninstalled one.</simpara></listitem>
117
<para>In a typical situation, the installed version of a package (priority 100)
118
is not as recent as one of the versions available from the sources listed in
119
the &sources-list; file (priority 500 or 990). Then the package will be upgraded
120
when <command>apt-get install <replaceable>some-package</replaceable></command>
121
or <command>apt-get upgrade</command> is executed.
124
<para>More rarely, the installed version of a package is <emphasis>more</emphasis> recent
125
than any of the other available versions. The package will not be downgraded
126
when <command>apt-get install <replaceable>some-package</replaceable></command>
127
or <command>apt-get upgrade</command> is executed.</para>
129
<para>Sometimes the installed version of a package is more recent than the
130
version belonging to the target release, but not as recent as a version
131
belonging to some other distribution. Such a package will indeed be upgraded
132
when <command>apt-get install <replaceable>some-package</replaceable></command>
133
or <command>apt-get upgrade</command> is executed,
134
because at least <emphasis>one</emphasis> of the available versions has a higher
135
priority than the installed version.</para>
138
<refsect2><title>The Effect of APT Preferences</title>
140
<para>The APT preferences file allows the system administrator to control the
141
assignment of priorities. The file consists of one or more multi-line records
142
separated by blank lines. Records can have one of two forms, a specific form
146
<simpara>The specific form assigns a priority (a "Pin-Priority") to a
147
specified package and specified version or version range. For example,
148
the following record assigns a high priority to all versions of
149
the <filename>perl</filename> package whose version number begins with "<literal>5.8</literal>".</simpara>
158
<listitem><simpara>The general form assigns a priority to all of the package versions in a
159
given distribution (that is, to all the versions of packages that are
160
listed in a certain <filename>Release</filename> file) or to all of the package
161
versions coming from a particular Internet site, as identified by the
162
site's fully qualified domain name.</simpara>
164
<simpara>This general-form entry in the APT preferences file applies only
165
to groups of packages. For example, the following record assigns a high
166
priority to all package versions available from the local site.</simpara>
174
<simpara>A note of caution: the keyword used here is "<literal>origin</literal>".
175
This should not be confused with the Origin of a distribution as
176
specified in a <filename>Release</filename> file. What follows the "Origin:" tag
177
in a <filename>Release</filename> file is not an Internet address
178
but an author or vendor name, such as "Debian" or "Ximian".</simpara>
180
<simpara>The following record assigns a low priority to all package versions
181
belonging to any distribution whose Archive name is "<literal>unstable</literal>".</simpara>
185
Pin: release a=unstable
189
<simpara>The following record assigns a high priority to all package versions
190
belonging to any release whose Archive name is "<literal>stable</literal>"
191
and whose release Version number is "<literal>3.0</literal>".</simpara>
195
Pin: release a=stable, v=3.0
205
<title>How APT Interprets Priorities</title>
208
Priorities (P) assigned in the APT preferences file must be positive
209
or negative integers. They are interpreted as follows (roughly speaking):
213
<term>P > 1000</term>
214
<listitem><simpara>causes a version to be installed even if this
215
constitutes a downgrade of the package</simpara></listitem>
218
<term>990 < P <=1000</term>
219
<listitem><simpara>causes a version to be installed
220
even if it does not come from the target release,
221
unless the installed version is more recent</simpara></listitem>
224
<term>500 < P <=990</term>
225
<listitem><simpara>causes a version to be installed
226
unless there is a version available belonging to the target release
227
or the installed version is more recent</simpara></listitem>
230
<term>100 < P <=500</term>
231
<listitem><simpara>causes a version to be installed
232
unless there is a version available belonging to some other
233
distribution or the installed version is more recent</simpara></listitem>
236
<term>0 < P <=100</term>
237
<listitem><simpara>causes a version to be installed
238
only if there is no installed version of the package</simpara></listitem>
241
<term>P < 0</term>
242
<listitem><simpara>prevents the version from being installed</simpara></listitem>
247
<para>If any specific-form records match an available package version then the
248
first such record determines the priority of the package version.
250
if any general-form records match an available package version then the
251
first such record determines the priority of the package version.</para>
253
<para>For example, suppose the APT preferences file contains the three
254
records presented earlier:</para>
266
Pin: release unstable
272
<listitem><simpara>The most recent available version of the <literal>perl</literal>
273
package will be installed, so long as that version's version number begins
274
with "<literal>5.8</literal>". If <emphasis>any</emphasis> 5.8* version of <literal>perl</literal> is
275
available and the installed version is 5.9*, then <literal>perl</literal> will be
276
downgraded.</simpara></listitem>
277
<listitem><simpara>A version of any package other than <literal>perl</literal>
278
that is available from the local system has priority over other versions,
279
even versions belonging to the target release.
280
</simpara></listitem>
281
<listitem><simpara>A version of a package whose origin is not the local
282
system but some other site listed in &sources-list; and which belongs to
283
an <literal>unstable</literal> distribution is only installed if it is selected
284
for installation and no version of the package is already installed.
285
</simpara></listitem>
291
<title>Determination of Package Version and Distribution Properties</title>
293
<para>The locations listed in the &sources-list; file should provide
294
<filename>Packages</filename> and <filename>Release</filename> files
295
to describe the packages available at that location. </para>
297
<para>The <filename>Packages</filename> file is normally found in the directory
298
<filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
299
for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
300
It consists of a series of multi-line records, one for each package available
301
in that directory. Only two lines in each record are relevant for setting
305
<term>the <literal>Package:</literal> line</term>
306
<listitem><simpara>gives the package name</simpara></listitem>
309
<term>the <literal>Version:</literal> line</term>
310
<listitem><simpara>gives the version number for the named package</simpara></listitem>
315
<para>The <filename>Release</filename> file is normally found in the directory
316
<filename>.../dists/<replaceable>dist-name</replaceable></filename>:
317
for example, <filename>.../dists/stable/Release</filename>,
318
or <filename>.../dists/woody/Release</filename>.
319
It consists of a single multi-line record which applies to <emphasis>all</emphasis> of
320
the packages in the directory tree below its parent. Unlike the
321
<filename>Packages</filename> file, nearly all of the lines in a <filename>Release</filename>
322
file are relevant for setting APT priorities:
326
<term>the <literal>Archive:</literal> line</term>
327
<listitem><simpara>names the archive to which all the packages
328
in the directory tree belong. For example, the line
330
specifies that all of the packages in the directory
331
tree below the parent of the <filename>Release</filename> file are in a
332
<literal>stable</literal> archive. Specifying this value in the APT preferences file
333
would require the line:
336
Pin: release a=stable
342
<term>the <literal>Version:</literal> line</term>
343
<listitem><simpara>names the release version. For example, the
344
packages in the tree might belong to Debian GNU/Linux release
345
version 3.0. Note that there is normally no version number for the
346
<literal>testing</literal> and <literal>unstable</literal> distributions because they
347
have not been released yet. Specifying this in the APT preferences
348
file would require one of the following lines.
353
Pin: release a=stable, v=3.0
361
<term>the <literal>Component:</literal> line</term>
362
<listitem><simpara>names the licensing component associated with the
363
packages in the directory tree of the <filename>Release</filename> file.
364
For example, the line "Component: main" specifies that
365
all the packages in the directory tree are from the <literal>main</literal>
366
component, which entails that they are licensed under terms listed
367
in the Debian Free Software Guidelines. Specifying this component
368
in the APT preferences file would require the line:
377
<term>the <literal>Origin:</literal> line</term>
378
<listitem><simpara>names the originator of the packages in the
379
directory tree of the <filename>Release</filename> file. Most commonly, this is
380
<literal>Debian</literal>. Specifying this origin in the APT preferences file
381
would require the line:
384
Pin: release o=Debian
390
<term>the <literal>Label:</literal> line</term>
391
<listitem><simpara>names the label of the packages in the directory tree
392
of the <filename>Release</filename> file. Most commonly, this is
393
<literal>Debian</literal>. Specifying this label in the APT preferences file
394
would require the line:
397
Pin: release l=Debian
404
<para>All of the <filename>Packages</filename> and <filename>Release</filename>
405
files retrieved from locations listed in the &sources-list; file are stored
406
in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
407
by the variable <literal>Dir::State::Lists</literal> in the <filename>apt.conf</filename> file.
408
For example, the file
409
<filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename>
410
contains the <filename>Release</filename> file retrieved from the site
411
<literal>debian.lcs.mit.edu</literal> for <literal>binary-i386</literal> architecture
412
files from the <literal>contrib</literal> component of the <literal>unstable</literal>
417
<title>Optional Lines in an APT Preferences Record</title>
419
<para>Each record in the APT preferences file can optionally begin with
420
one or more lines beginning with the word <literal>Explanation:</literal>.
421
This provides a place for comments.</para>
423
<para>The <literal>Pin-Priority:</literal> line in each APT preferences record is
424
optional. If omitted, APT assigs a priority of 1 less than the last value
425
specified on a line beginning with <literal>Pin-Priority: release ...</literal>.</para>
430
<title>Examples</title>
432
<title>Tracking Stable</title>
434
<para>The following APT preferences file will cause APT to assign a
435
priority higher than the default (500) to all package versions belonging
436
to a <literal>stable</literal> distribution and a prohibitively low priority to
437
package versions belonging to other <literal>Debian</literal> distributions.
440
Explanation: Uninstall or do not install any Debian-originated
441
Explanation: package versions other than those in the stable distro
443
Pin: release a=stable
447
Pin: release o=Debian
452
<para>With a suitable &sources-list; file and the above preferences file,
453
any of the following commands will cause APT to upgrade to the
454
latest <literal>stable</literal> version(s).
457
apt-get install <replaceable>package-name</replaceable>
463
<para>The following command will cause APT to upgrade the specified
464
package to the latest version from the <literal>testing</literal> distribution;
465
the package will not be upgraded again unless this command is given
469
apt-get install <replaceable>package</replaceable>/testing
475
<title>Tracking Testing or Unstable</title>
477
<para>The following APT preferences file will cause APT to assign
478
a high priority to package versions from the <literal>testing</literal>
479
distribution, a lower priority to package versions from the
480
<literal>unstable</literal> distribution, and a prohibitively low priority
481
to package versions from other <literal>Debian</literal> distributions.
485
Pin: release a=testing
489
Pin: release a=unstable
493
Pin: release o=Debian
498
<para>With a suitable &sources-list; file and the above preferences file,
499
any of the following commands will cause APT to upgrade to the latest
500
<literal>testing</literal> version(s).
503
apt-get install <replaceable>package-name</replaceable>
509
<para>The following command will cause APT to upgrade the specified
510
package to the latest version from the <literal>unstable</literal> distribution.
511
Thereafter, <command>apt-get upgrade</command> will upgrade
512
the package to the most recent <literal>testing</literal> version if that is
513
more recent than the installed version, otherwise, to the most recent
514
<literal>unstable</literal> version if that is more recent than the installed
518
apt-get install <replaceable>package</replaceable>/unstable
526
<title>See Also</title>
527
<para>&apt-get; &apt-cache; &apt-conf; &sources-list;
added
removed
doc/apt_preferences.5.xml
