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