- initial import of revision 374 from cnc
[apt.git] / doc / apt_preferences.5.sgml
1 <!-- -*- mode: sgml; mode: fold -*- -->
2 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
3
4 <!ENTITY % aptent SYSTEM "apt.ent">
5 %aptent;
6
7 ]>
8
9 <refentry>
10  &apt-docinfo;
11
12  <refmeta>
13    <refentrytitle>apt_preferences</>
14    <manvolnum>5</>
15  </refmeta>
16
17  <!-- Man page title -->
18  <refnamediv>
19     <refname>apt_preferences</>
20     <refpurpose>Preference control file for APT</>
21  </refnamediv>
22
23 <RefSect1>
24 <Title>Description</Title>
25 <para>
26 The APT preferences file <filename>/etc/apt/preferences</>
27 can be used to control which versions of packages will be selected
28 for installation.
29 </para>
30
31 <para>
32 Several versions of a package may be available for installation when
33 the &sources-list; file contains references to more than one distribution
34 (for example, <literal>stable</literal> and <literal>testing</literal>).
35 APT assigns a priority to each version that is available.
36 Subject to dependency constraints, <command>apt-get</command> selects the
37 version with the highest priority for installation.
38 The APT preferences file overrides the priorities that APT assigns to
39 package versions by default, thus giving the user control over which
40 one is selected for installation.
41 </para>
42 <para>
43 Several instances of the same version of a package may be available when
44 the &sources-list; file contains references to more than one source.
45 In this case <command>apt-get</command> downloads the instance listed
46 earliest in the &sources-list; file.
47 The APT preferences file does not affect the choice of instance, only
48 the choice of version.
49 </para>
50
51 <RefSect2><Title>APT's Default Priority Assignments</>
52
53 <para>
54 If there is no preferences file or if there is no entry in the file
55 that applies to a particular version then the priority assigned to that
56 version is the priority of the distribution to which that version
57 belongs.  It is possible to single out a distribution, "the target release",
58 which receives a higher priority than other distributions do by default.
59 The target release can be set on the <command>apt-get</command> command
60 line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>.
61 For example,
62 <programlisting>
63 <command>apt-get install -t testing <replaceable>some-package</replaceable></command>
64 </programlisting>
65 <programlisting>
66 APT::Default-Release "stable";
67 </programlisting>
68 </para>
69
70 <para>
71 If the target release has been specified then APT uses the following
72 algorithm to set the priorities of the versions of a package.  Assign:
73 <variablelist>
74 <varlistentry>
75 <term>priority 100</term>
76 <listitem><simpara>to the version that is already installed (if any).</simpara></listitem>
77 </varlistentry>
78 <varlistentry>
79 <term>priority 500</term>
80 <listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem>
81 </varlistentry>
82 <varlistentry>
83 <term>priority 990</term>
84 <listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
85 </varlistentry>
86 </variablelist>
87 </para>
88
89 <para>
90 If the target release has not been specified then APT simply assigns
91 priority 100 to all installed package versions and priority 500 to all
92 uninstalled package versions.
93 </para>
94
95 <para>
96 APT then applies the following rules, listed in order of precedence,
97 to determine which version of a package to install.
98 <itemizedlist>
99 <listitem><simpara>Never downgrade unless the priority of an available
100 version exceeds 1000.  ("Downgrading" is installing a less recent version
101 of a package in place of a more recent version.  Note that none of APT's
102 default priorities exceeds 1000; such high priorities can only be set in
103 the preferences file.  Note also that downgrading a package
104 can be risky.)</simpara></listitem>
105 <listitem><simpara>Install the highest priority version.</simpara></listitem>
106 <listitem><simpara>If two or more versions have the same priority,
107 install the most recent one (that is, the one with the higher version
108 number).</simpara></listitem>
109 <listitem><simpara>If two or more versions have the same priority and
110 version number but either the packages differ in some of their metadata or the
111 <literal/--reinstall/ option is given, install the uninstalled one.</simpara></listitem>
112 </itemizedlist>
113 </para>
114
115 <para>
116 In a typical situation, the installed version of a package (priority 100)
117 is not as recent as one of the versions available from the sources listed in
118 the &sources-list; file (priority 500 or 990).  Then the package will be upgraded
119 when <command>apt-get install <replaceable>some-package</replaceable></command>
120 or <command>apt-get upgrade</command> is executed.
121 </para>
122
123 <para>
124 More rarely, the installed version of a package is <emphasis/more/ 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.
128 </para>
129
130 <para>
131 Sometimes the installed version of a package is more recent than the
132 version belonging to the target release, but not as recent as a version
133 belonging to some other distribution.  Such a package will indeed be upgraded
134 when <command>apt-get install <replaceable>some-package</replaceable></command>
135 or <command>apt-get upgrade</command> is executed,
136 because at least <emphasis/one/ of the available versions has a higher
137 priority than the installed version.
138 </para>
139
140 </RefSect2>
141
142 <RefSect2><Title>The Effect of APT Preferences</>
143
144 <para>
145 The APT preferences file allows the system administrator to control the
146 assignment of priorities.  The file consists of one or more multi-line records
147 separated by blank lines.  Records can have one of two forms, a specific form
148 and a general form.
149 <itemizedlist>
150 <listitem>
151 <simpara>
152 The specific form assigns a priority (a "Pin-Priority") to a
153 specified package and specified version or version range.  For example,
154 the following record assigns a high priority to all versions of
155 the <filename/perl/ package whose version number begins with "<literal/5.8/".
156 </simpara>
157
158 <programlisting>
159 Package: perl
160 Pin: version 5.8*
161 Pin-Priority: 1001
162 </programlisting>
163 </listitem>
164
165 <listitem><simpara>
166 The general form assigns a priority to all of the package versions in a
167 given distribution (that is, to all the versions of packages that are
168 listed in a certain <filename/Release/ file) or to all of the package
169 versions coming from a particular Internet site, as identified by the
170 site's fully qualified domain name.
171 </simpara>
172
173 <simpara>
174 This general-form entry in the APT preferences file applies only
175 to groups of packages.  For example, the following record assigns a high
176 priority to all package versions available from the local site.
177 </simpara>
178
179 <programlisting>
180 Package: *
181 Pin: origin ""
182 Pin-Priority: 999
183 </programlisting>
184
185 <simpara>
186 A note of caution: the keyword used here is "<literal/origin/".
187 This should not be confused with the Origin of a distribution as
188 specified in a <filename/Release/ file.  What follows the "Origin:" tag
189 in a <filename/Release/ file is not an Internet address
190 but an author or vendor name, such as "Debian" or "Ximian".
191 </simpara>
192
193 <simpara>
194 The following record assigns a low priority to all package versions
195 belonging to any distribution whose Archive name is "<literal/unstable/".
196 </simpara>
197
198 <programlisting>
199 Package: *
200 Pin: release a=unstable
201 Pin-Priority: 50
202 </programlisting>
203
204 <simpara>
205 The following record assigns a high priority to all package versions
206 belonging to any release whose Archive name is "<literal/stable/"
207 and whose release Version number is "<literal/3.0/".
208 </simpara>
209
210 <programlisting>
211 Package: *
212 Pin: release a=unstable, v=3.0
213 Pin-Priority: 50
214 </programlisting>
215 </listitem>
216 </itemizedlist>
217 </para>
218
219 </RefSect2>
220
221 <RefSect2>
222 <Title>How APT Interprets Priorities</Title>
223
224 <para>
225 Priorities (P) assigned in the APT preferences file must be positive
226 or negative integers.  They are interpreted as follows (roughly speaking):
227
228 <variablelist>
229 <varlistentry>
230 <term>P &gt; 1000</term>
231 <listitem><simpara>causes a version to be installed even if this
232 constitutes a downgrade of the package</simpara></listitem>
233 </varlistentry>
234 <varlistentry>
235 <term>990 &lt; P &lt;=1000</term>
236 <listitem><simpara>causes a version to be installed
237 even if it does not come from the target release,
238 unless the installed version is more recent</simpara></listitem>
239 </varlistentry>
240 <varlistentry>
241 <term>500 &lt; P &lt;=990</term>
242 <listitem><simpara>causes a version to be installed
243 unless there is a version available belonging to the target release
244 or the installed version is more recent</simpara></listitem>
245 </varlistentry>
246 <varlistentry>
247 <term>100 &lt; P &lt;=500</term>
248 <listitem><simpara>causes a version to be installed
249 unless there is a version available belonging to some other
250 distribution or the installed version is more recent</simpara></listitem>
251 </varlistentry>
252 <varlistentry>
253 <term>0 &lt; P &lt;=100</term>
254 <listitem><simpara>causes a version to be installed
255 only if there is no installed version of the package</simpara></listitem>
256 </varlistentry>
257 <varlistentry>
258 <term>P &lt; 0</term>
259 <listitem><simpara>prevents the version from being installed</simpara></listitem>
260 </varlistentry>
261 </variablelist>
262 </para>
263
264 <para>
265 If any specific-form records match an available package version then the
266 first such record determines the priority of the package version.  
267 Failing that,
268 if any general-form records match an available package version then the
269 first such record determines the priority of the package version.  
270 </para>
271
272 <para>
273 For example, suppose the APT preferences file contains the three
274 records presented earlier:
275
276 <programlisting>
277 Package: perl
278 Pin: version 5.8*
279 Pin-Priority: 1001
280
281 Package: *
282 Pin: origin ""
283 Pin-Priority: 999
284
285 Package: *
286 Pin: release unstable
287 Pin-Priority: 50
288 </programlisting>
289
290 Then:
291
292 <itemizedlist>
293 <listitem><simpara>The most recent available version of the <literal/perl/
294 package will be installed, so long as that version's version number begins
295 with "<literal/5.8/".  If <emphasis/any/ 5.8* version of <literal/perl/ is
296 available and the installed version is 5.9*, then <literal/perl/ will be
297 downgraded.</simpara></listitem>
298 <listitem><simpara>A version of any package other than <literal/perl/
299 that is available from the local system has priority over other versions,
300 even versions belonging to the target release.
301 </simpara></listitem>
302 <listitem><simpara>A version of a package whose origin is not the local
303 system but some other site listed in &sources-list; and which belongs to
304 an <literal/unstable/ distribution is only installed if it is selected
305 for installation and no version of the package is already installed.
306 </simpara></listitem>
307 </itemizedlist>
308 </para>
309 </RefSect2>
310
311 <RefSect2>
312 <Title>Determination of Package Version and Distribution Properties</Title>
313
314 <para>
315 The locations listed in the &sources-list; file should provide
316 <filename>Packages</filename> and <filename>Release</filename> files
317 to describe the packages available at that location.
318 </para>
319
320 <para>
321 The <filename>Packages</filename> file is normally found in the directory
322 <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
323 for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
324 It consists of a series of multi-line records, one for each package available
325 in that directory.  Only two lines in each record are relevant for setting
326 APT priorities:
327 <variablelist>
328 <varlistentry>
329 <term>the <literal/Package:/ line</term>
330 <listitem><simpara>gives the package name</simpara></listitem>
331 </varlistentry>
332 <varlistentry>
333 <term>the <literal/Version:/ line</term>
334 <listitem><simpara>gives the version number for the named package</simpara></listitem>
335 </varlistentry>
336 </variablelist>
337 </para>
338
339 <para>
340 The <filename>Release</filename> file is normally found in the directory
341 <filename>.../dists/<replaceable>dist-name</replaceable></filename>:
342 for example, <filename>.../dists/stable/Release</filename>,
343 or <filename>.../dists/woody/Release</filename>.
344 It consists of a single multi-line record which applies to <emphasis/all/ of
345 the packages in the directory tree below its parent.  Unlike the
346 <filename/Packages/ file, nearly all of the lines in a <filename/Release/
347 file are relevant for setting APT priorities:
348
349 <variablelist>
350 <varlistentry>
351 <term>the <literal/Archive:/ line</term>
352 <listitem><simpara>names the archive to which all the packages
353 in the directory tree belong.  For example, the line
354 "Archive: stable"
355 specifies that all of the packages in the directory
356 tree below the parent of the <filename/Release/ file are in a
357 <literal/stable/ archive.  Specifying this value in the APT preferences file
358 would require the line:
359 </simpara>
360 <programlisting>
361 Pin: release a=stable
362 </programlisting>
363 </listitem>
364 </varlistentry>
365
366 <varlistentry>
367 <term>the <literal/Version:/ line</term>
368 <listitem><simpara>names the release version.  For example, the
369 packages in the tree might belong to Debian GNU/Linux release
370 version 3.0.  Note that there is normally no version number for the
371 <literal/testing/ and <literal/unstable/ distributions because they
372 have not been released yet.  Specifying this in the APT preferences
373 file would require one of the following lines.
374 </simpara>
375
376 <programlisting>
377 Pin: release v=3.0
378 Pin: release a=stable, v=3.0
379 Pin: release 3.0
380 </programlisting>
381
382 </listitem>
383 </varlistentry>
384
385 <varlistentry>
386 <term>the <literal/Component:/ line</term>
387 <listitem><simpara>names the licensing component associated with the
388 packages in the directory tree of the <filename/Release/ file.
389 For example, the line "Component: main" specifies that
390 all the packages in the directory tree are from the <literal/main/
391 component, which entails that they are licensed under terms listed
392 in the Debian Free Software Guidelines.  Specifying this component
393 in the APT preferences file would require the line:
394 </simpara>
395 <programlisting>
396 Pin: release c=main
397 </programlisting>
398 </listitem>
399 </varlistentry>
400
401 <varlistentry>
402 <term>the <literal/Origin:/ line</term>
403 <listitem><simpara>names the originator of the packages in the
404 directory tree of the <filename/Release/ file.  Most commonly, this is
405 <literal/Debian/.  Specifying this origin in the APT preferences file
406 would require the line:
407 </simpara>
408 <programlisting>
409 Pin: release o=Debian
410 </programlisting>
411 </listitem>
412 </varlistentry>
413
414 <varlistentry>
415 <term>the <literal/Label:/ line</term>
416 <listitem><simpara>names the label of the packages in the directory tree
417 of the <filename/Release/ file.  Most commonly, this is
418 <literal/Debian/.  Specifying this label in the APT preferences file
419 would require the line:
420 </simpara>
421 <programlisting>
422 Pin: release l=Debian
423 </programlisting>
424 </listitem>
425 </varlistentry>
426 </variablelist>
427 </para>
428
429 <para>
430 All of the <filename>Packages</filename> and <filename>Release</filename>
431 files retrieved from locations listed in the &sources-list; file are stored
432 in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
433 by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file.
434 For example, the file
435 <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename>
436 contains the <filename>Release</filename> file retrieved from the site
437 <literal/debian.lcs.mit.edu/ for <literal/binary-i386/ architecture
438 files from the <literal/contrib/ component of the <literal/unstable/
439 distribution.
440 </para>
441
442 </RefSect2>
443
444 <RefSect2>
445 <Title>Optional Lines in an APT Preferences Record</Title>
446
447 <para>
448 Each record in the APT preferences file can optionally begin with
449 one or more lines beginning with the word <literal/Explanation:/.
450 This provides a place for comments.
451 </para>
452
453 <para>
454 The <literal/Pin-Priority:/ line in each APT preferences record is
455 optional.  If omitted, APT assigs a priority of 1 less than the last value
456 specified on a line beginning with <literal/Pin-Priority: release .../.
457 </para>
458 </RefSect2>
459 </RefSect1>
460
461 <RefSect1>
462 <Title>Examples</Title>
463 <RefSect2>
464 <Title>Tracking Stable</Title>
465
466 <para>
467 The following APT preferences file will cause APT to assign a
468 priority higher than the default (500) to all package versions belonging
469 to a <literal/stable/ distribution and a prohibitively low priority to
470 package versions belonging to other <literal/Debian/ distributions.
471
472 <programlisting>
473 Explanation: Uninstall or do not install any Debian-originated
474 Explanation: package versions other than those in the stable distro
475 Package: *
476 Pin: release a=stable
477 Pin-Priority: 900
478
479 Package: *
480 Pin: release o=Debian
481 Pin-Priority: -10
482 </programlisting>
483 </para>
484
485 <para>
486 With a suitable &sources-list; file and the above preferences file,
487 any of the following commands will cause APT to upgrade to the
488 latest <literal/stable/ version(s).
489
490 <programlisting>
491 apt-get install <replaceable>package-name</replaceable>
492 apt-get upgrade
493 apt-get dist-upgrade
494 </programlisting>
495 </para>
496
497 <para>
498 The following command will cause APT to upgrade the specified
499 package to the latest version from the <literal/testing/ distribution;
500 the package will not be upgraded again unless this command is given
501 again.
502
503 <programlisting>
504 apt-get install <replaceable>package</replaceable>/testing
505 </programlisting>
506 </para>
507 </RefSect2>
508
509  <RefSect2>
510  <Title>Tracking Testing or Unstable</Title>
511
512 <para>
513 The following APT preferences file will cause APT to assign
514 a high priority to package versions from the <literal/testing/
515 distribution, a lower priority to package versions from the
516 <literal/unstable/ distribution, and a prohibitively low priority
517 to package versions from other <literal/Debian/ distributions.
518
519 <programlisting>
520 Package: *
521 Pin: release a=testing
522 Pin-Priority: 900
523
524 Package: *
525 Pin: release a=unstable
526 Pin-Priority: 800
527
528 Package: *
529 Pin: release o=Debian
530 Pin-Priority: -10
531 </programlisting>
532 </para>
533
534 <para>
535 With a suitable &sources-list; file and the above preferences file,
536 any of the following commands will cause APT to upgrade to the latest
537 <literal/testing/ version(s).
538
539 <programlisting>
540 apt-get install <replaceable>package-name</replaceable>
541 apt-get upgrade
542 apt-get dist-upgrade
543 </programlisting>
544 </para>
545
546 <para>The following command will cause APT to upgrade the specified
547 package to the latest version from the <literal/unstable/ distribution.
548 Thereafter, <command>apt-get upgrade</command> will upgrade
549 the package to the most recent <literal/testing/ version if that is
550 more recent than the installed version, otherwise, to the most recent
551 <literal/unstable/ version if that is more recent than the installed
552 version.
553
554 <programlisting>
555 apt-get install <replaceable>package</replaceable>/unstable
556 </programlisting>
557 </para>
558
559 </RefSect2>
560 </RefSect1>
561
562 <RefSect1>
563 <Title>See Also</Title>
564 <para>
565 &apt-get; &apt-cache; &apt-conf; &sources-list;
566 </para>
567 </RefSect1>
568
569  &manbugs;
570  &manauthor;
571
572 </refentry>