doc/apt_preferences.5

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