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