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