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 <term>0 &lt; P &lt;=100</term>
 253 <listitem><simpara>causes a version to be installed
 254 only if there is no installed version of the package</simpara></listitem>
 255 </varlistentry>
 256 <varlistentry>
 257 <term>P &lt; 0</term>
 258 <listitem><simpara>prevents the version from being installed</simpara></listitem>
 259 </varlistentry>
 260 </variablelist>
 261 </para>
 262
 263 <para>
 264 If any specific-form records match an available package version then the
 265 first such record determines the priority of the package version.
 266 Failing that,
 267 if any general-form records match an available package version then the
 268 first such record determines the priority of the package version.
 269 </para>
 270
 271 <para>
 272 For example, suppose the APT preferences file contains the three
 273 records presented earlier:
 274
 275 <programlisting>
 276 Package: perl
 277 Pin: version 5.8*
 278 Pin-Priority: 1001
 279
 280 Package: *
 281 Pin: origin ""
 282 Pin-Priority: 999
 283
 284 Package: *
 285 Pin: release unstable
 286 Pin-Priority: 50
 287 </programlisting>
 288
 289 Then:
 290
 291 <itemizedlist>
 292 <listitem><simpara>The most recent available version of the <literal/perl/
 293 package will be installed, so long as that version's version number begins
 294 with "<literal/5.8/".  If <emphasis/any/ 5.8* version of <literal/perl/ is
 295 available and the installed version is 5.9*, then <literal/perl/ will be
 296 downgraded.</simpara></listitem>
 297 <listitem><simpara>A version of any package other than <literal/perl/
 298 that is available from the local system has priority over other versions,
 299 even versions belonging to the target release.
 300 </simpara></listitem>
 301 <listitem><simpara>A version of a package whose origin is not the local
 302 system but some other site listed in &sources-list; and which belongs to
 303 an <literal/unstable/ distribution is only installed if it is selected
 304 for installation and no version of the package is already installed.
 305 </simpara></listitem>
 306 </itemizedlist>
 307 </para>
 308 </RefSect2>
 309
 310 <RefSect2>
 311 <Title>Determination of Package Version and Distribution Properties</Title>
 312
 313 <para>
 314 The locations listed in the &sources-list; file should provide
 315 <filename>Packages</filename> and <filename>Release</filename> files
 316 to describe the packages available at that location.
 317 </para>
 318
 319 <para>
 320 The <filename>Packages</filename> file is normally found in the directory
 321 <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
 322 for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
 323 It consists of a series of multi-line records, one for each package available
 324 in that directory.  Only two lines in each record are relevant for setting
 325 APT priorities:
 326 <variablelist>
 327 <varlistentry>
 328 <term>the <literal/Package:/ line</term>
 329 <listitem><simpara>gives the package name</simpara></listitem>
 330 </varlistentry>
 331 <varlistentry>
 332 <term>the <literal/Version:/ line</term>
 333 <listitem><simpara>gives the version number for the named package</simpara></listitem>
 334 </varlistentry>
 335 </variablelist>
 336 </para>
 337
 338 <para>
 339 The <filename>Release</filename> file is normally found in the directory
 340 <filename>.../dists/<replaceable>dist-name</replaceable></filename>:
 341 for example, <filename>.../dists/stable/Release</filename>,
 342 or <filename>.../dists/woody/Release</filename>.
 343 It consists of a single multi-line record which applies to <emphasis/all/ of
 344 the packages in the directory tree below its parent.  Unlike the
 345 <filename/Packages/ file, nearly all of the lines in a <filename/Release/
 346 file are relevant for setting APT priorities:
 347
 348 <variablelist>
 349 <varlistentry>
 350 <term>the <literal/Archive:/ line</term>
 351 <listitem><simpara>names the archive to which all the packages
 352 in the directory tree belong.  For example, the line
 353 "Archive: stable"
 354 specifies that all of the packages in the directory
 355 tree below the parent of the <filename/Release/ file are in a
 356 <literal/stable/ archive.  Specifying this value in the APT preferences file
 357 would require the line:
 358 </simpara>
 359 <programlisting>
 360 Pin: release a=stable
 361 </programlisting>
 362 </listitem>
 363 </varlistentry>
 364
 365 <varlistentry>
 366 <term>the <literal/Version:/ line</term>
 367 <listitem><simpara>names the release version.  For example, the
 368 packages in the tree might belong to Debian GNU/Linux release
 369 version 3.0.  Note that there is normally no version number for the
 370 <literal/testing/ and <literal/unstable/ distributions because they
 371 have not been released yet.  Specifying this in the APT preferences
 372 file would require one of the following lines.
 373 </simpara>
 374
 375 <programlisting>
 376 Pin: release v=3.0
 377 Pin: release a=stable v=3.0
 378 Pin: release 3.0
 379 </programlisting>
 380
 381 </listitem>
 382 </varlistentry>
 383
 384 <varlistentry>
 385 <term>the <literal/Component:/ line</term>
 386 <listitem><simpara>names the licensing component associated with the
 387 packages in the directory tree of the <filename/Release/ file.
 388 For example, the line "Component: main" specifies that
 389 all the packages in the directory tree are from the <literal/main/
 390 component, which entails that they are licensed under terms listed
 391 in the Debian Free Software Guidelines.  Specifying this component
 392 in the APT preferences file would require the line:
 393 </simpara>
 394 <programlisting>
 395 Pin: release c=main
 396 </programlisting>
 397 </listitem>
 398 </varlistentry>
 399
 400 <varlistentry>
 401 <term>the <literal/Origin:/ line</term>
 402 <listitem><simpara>names the originator of the packages in the
 403 directory tree of the <filename/Release/ file.  Most commonly, this is
 404 <literal/Debian/.  Specifying this origin in the APT preferences file
 405 would require the line:
 406 </simpara>
 407 <programlisting>
 408 Pin: release o=Debian
 409 </programlisting>
 410 </listitem>
 411 </varlistentry>
 412
 413 <varlistentry>
 414 <term>the <literal/Label:/ line</term>
 415 <listitem><simpara>names the label of the packages in the directory tree
 416 of the <filename/Release/ file.  Most commonly, this is
 417 <literal/Debian/.  Specifying this label in the APT preferences file
 418 would require the line:
 419 </simpara>
 420 <programlisting>
 421 Pin: release l=Debian
 422 </programlisting>
 423 </listitem>
 424 </varlistentry>
 425 </variablelist>
 426 </para>
 427
 428 <para>
 429 All of the <filename>Packages</filename> and <filename>Release</filename>
 430 files retrieved from locations listed in the &sources-list; file are stored
 431 in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
 432 by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file.
 433 For example, the file
 434 <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename>
 435 contains the <filename>Release</filename> file retrieved from the site
 436 <literal/debian.lcs.mit.edu/ for <literal/binary-i386/ architecture
 437 files from the <literal/contrib/ component of the <literal/unstable/
 438 distribution.
 439 </para>
 440
 441 </RefSect2>
 442
 443 <RefSect2>
 444 <Title>Optional Lines in an APT Preferences Record</Title>
 445
 446 <para>
 447 Each record in the APT preferences file can optionally begin with
 448 one or more lines beginning with the word <literal/Explanation:/.
 449 This provides a place for comments.
 450 </para>
 451
 452 <para>
 453 The <literal/Pin-Priority:/ line in each APT preferences record is
 454 optional.  If omitted, APT assigs a priority of 1 less than the last value
 455 specified on a line beginning with <literal/Pin-Priority: release .../.
 456 </para>
 457 </RefSect2>
 458 </RefSect1>
 459
 460 <RefSect1>
 461 <Title>Examples</Title>
 462 <RefSect2>
 463 <Title>Tracking Stable</Title>
 464
 465 <para>
 466 The following APT preferences file will cause APT to assign a
 467 priority higher than the default (500) to all package versions belonging
 468 to a <literal/stable/ distribution and a prohibitively low priority to
 469 package versions belonging to other <literal/Debian/ distributions.
 470
 471 <programlisting>
 472 Explanation: Uninstall or do not install any Debian-originated
 473 Explanation: package versions other than those in the stable distro
 474 Package: *
 475 Pin: release a=stable
 476 Pin-Priority: 900
 477
 478 Package: *
 479 Pin: release o=Debian
 480 Pin-Priority: -10
 481 </programlisting>
 482 </para>
 483
 484 <para>
 485 With a suitable &sources-list; file and the above preferences file,
 486 any of the following commands will cause APT to upgrade to the
 487 latest <literal/stable/ version(s).
 488
 489 <programlisting>
 490 apt-get install <replaceable>package-name</replaceable>
 491 apt-get upgrade
 492 apt-get dist-upgrade
 493 </programlisting>
 494 </para>
 495
 496 <para>
 497 The following command will cause APT to upgrade the specified
 498 package to the latest version from the <literal/testing/ distribution;
 499 the package will not be upgraded again unless this command is given
 500 again.
 501
 502 <programlisting>
 503 apt-get install <replaceable>package</replaceable>/testing
 504 </programlisting>
 505 </RefSect2>
 506
 507  <RefSect2>
 508  <Title>Tracking Testing or Unstable</Title>
 509
 510 <para>
 511 The following APT preferences file will cause APT to assign
 512 a high priority to package versions from the <literal/testing/
 513 distribution, a lower priority to package versions from the
 514 <literal/unstable/ distribution, and a prohibitively low priority
 515 to package versions from other <literal/Debian/ distributions.
 516
 517 <programlisting>
 518 Package: *
 519 Pin: release a=testing
 520 Pin-Priority: 900
 521
 522 Package: *
 523 Pin: release a=unstable
 524 Pin-Priority: 800
 525
 526 Package: *
 527 Pin: release o=Debian
 528 Pin-Priority: -10
 529 </programlisting>
 530 </para>
 531
 532 <para>
 533 With a suitable &sources-list; file and the above preferences file,
 534 any of the following commands will cause APT to upgrade to the latest
 535 <literal/testing/ version(s).
 536
 537 <programlisting>
 538 apt-get install <replaceable>package-name</replaceable>
 539 apt-get upgrade
 540 apt-get dist-upgrade
 541 </programlisting>
 542 </para>
 543
 544 <para>The following command will cause APT to upgrade the specified
 545 package to the latest version from the <literal/unstable/ distribution.
 546 Thereafter, <command>apt-get upgrade</command> will upgrade
 547 the package to the most recent <literal/testing/ version if that is
 548 more recent than the installed version, otherwise, to the most recent
 549 <literal/unstable/ version if that is more recent than the installed
 550 version.
 551
 552 <programlisting>
 553 apt-get install <replaceable>package</replaceable>/unstable
 554 </programlisting>
 555 </para>
 556
 557 </RefSect2>
 558 </RefSect1>
 559
 560 <RefSect1>
 561 <Title>See Also</Title>
 562 <para>
 563 &apt-get; &apt-cache; &apt-conf; &sources-list;
 564 </para>
 565 </RefSect1>
 566
 567  &manbugs;
 568  &manauthor;
 569
 570 </refentry>