1APT_PREFERENCES(5)                    APT                   APT_PREFERENCES(5)
2
3
4

NAME

6       apt_preferences - Preference control file for APT
7

DESCRIPTION

9       The APT preferences file /etc/apt/preferences and the fragment files in
10       the /etc/apt/preferences.d/ folder can be used to control which
11       versions of packages will be selected for installation.
12
13       Several versions of a package may be available for installation when
14       the sources.list(5) file contains references to more than one
15       distribution (for example, stable and testing). APT assigns a priority
16       to each version that is available. Subject to dependency constraints,
17       apt-get selects the version with the highest priority for installation.
18       The APT preferences override the priorities that APT assigns to package
19       versions by default, thus giving the user control over which one is
20       selected for installation.
21
22       Several instances of the same version of a package may be available
23       when the sources.list(5) file contains references to more than one
24       source. In this case apt-get downloads the instance listed earliest in
25       the sources.list(5) file. The APT preferences do not affect the choice
26       of instance, only the choice of version.
27
28       Preferences are a strong power in the hands of a system administrator
29       but they can become also their biggest nightmare if used without care!
30       APT will not question the preferences, so wrong settings can lead to
31       uninstallable packages or wrong decisions while upgrading packages.
32       Even more problems will arise if multiple distribution releases are
33       mixed without a good understanding of the following paragraphs.
34       Packages included in a specific release aren't tested in (and therefore
35       don't always work as expected in) older or newer releases, or together
36       with other packages from different releases. You have been warned.
37
38       Note that the files in the /etc/apt/preferences.d directory are parsed
39       in alphanumeric ascending order and need to obey the following naming
40       convention: The files have either no or "pref" as filename extension
41       and only contain alphanumeric, hyphen (-), underscore (_) and period
42       (.) characters. Otherwise APT will print a notice that it has ignored a
43       file, unless that file matches a pattern in the
44       Dir::Ignore-Files-Silently configuration list - in which case it will
45       be silently ignored.
46
47   APT's Default Priority Assignments
48       If there is no preferences file or if there is no entry in the file
49       that applies to a particular version then the priority assigned to that
50       version is the priority of the distribution to which that version
51       belongs. It is possible to single out a distribution, "the target
52       release", which receives a higher priority than other distributions do
53       by default. The target release can be set on the apt-get command line
54       or in the APT configuration file /etc/apt/apt.conf. Note that this has
55       precedence over any general priority you set in the
56       /etc/apt/preferences file described later, but not over specifically
57       pinned packages. For example,
58
59           apt-get install -t testing some-package
60
61
62
63           APT::Default-Release "stable";
64
65       If the target release has been specified then APT uses the following
66       algorithm to set the priorities of the versions of a package. Assign:
67
68       priority 1
69           to the versions coming from archives which in their Release files
70           are marked as "NotAutomatic: yes" but not as "ButAutomaticUpgrades:
71           yes" like the Debian experimental archive, as well as versions that
72           are not phased on this systems.
73
74       priority 100
75           to the version that is already installed (if any) and to the
76           versions coming from archives which in their Release files are
77           marked as "NotAutomatic: yes" and "ButAutomaticUpgrades: yes" like
78           the Debian backports archive since squeeze-backports.
79
80       priority 500
81           to the versions that do not belong to the target release.
82
83       priority 990
84           to the versions that belong to the target release.
85       The highest of those priorities whose description matches the version
86       is assigned to the version.
87
88       If the target release has not been specified then APT simply assigns
89       priority 100 to all installed package versions and priority 500 to all
90       uninstalled package versions, except versions coming from archives
91       which in their Release files are marked as "NotAutomatic: yes" - these
92       versions get the priority 1 or priority 100 if it is additionally
93       marked as "ButAutomaticUpgrades: yes".
94
95       APT then applies the following rules, listed in order of precedence, to
96       determine which version of a package to install.
97
98       •   Never downgrade unless the priority of an available version exceeds
99           1000. ("Downgrading" is installing a less recent version of a
100           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
102           set in the preferences file. Note also that downgrading a package
103           can be risky.)
104
105       •   Install the highest priority version.
106
107       •   If two or more versions have the same priority, install the most
108           recent one (that is, the one with the higher version number).
109
110       •   If two or more versions have the same priority and version number
111           but either the packages differ in some of their metadata or the
112           --reinstall option is given, install the uninstalled one.
113
114       In a typical situation, the installed version of a package (priority
115       100) is not as recent as one of the versions available from the sources
116       listed in the sources.list(5) file (priority 500 or 990). Then the
117       package will be upgraded when apt-get install some-package or apt-get
118       upgrade is executed.
119
120       More rarely, the installed version of a package is more recent than any
121       of the other available versions. The package will not be downgraded
122       when apt-get install some-package or apt-get upgrade is executed.
123
124       Sometimes the installed version of a package is more recent than the
125       version belonging to the target release, but not as recent as a version
126       belonging to some other distribution. Such a package will indeed be
127       upgraded when apt-get install some-package or apt-get upgrade is
128       executed, because at least one of the available versions has a higher
129       priority than the installed version.
130
131   Phased Updates
132       APT understands a field called Phased-Update-Percentage which can be
133       used to control the rollout of a new version. It is an integer between
134       0 and 100.
135
136       A system's eligibility to a phased update is determined by seeding
137       random number generator with the package source name, the version
138       number, and /etc/machine-id, and then calculating an integer in the
139       range [0, 100]. If this integer is larger than the
140       Phased-Update-Percentage, the version is pinned to 1, and thus held
141       back. Otherwise, normal policy rules apply.
142
143       In case you have multiple systems that you want to receive the same set
144       of updates, you can set APT::Machine-ID to a UUID such that they all
145       phase the same, or set APT::Get::Never-Include-Phased-Updates or
146       APT::Get::Always-Include-Phased-Updates to true such that APT will
147       never/always consider phased updates.
148
149   The Effect of APT Preferences
150       The APT preferences file allows the system administrator to control the
151       assignment of priorities. The file consists of one or more multi-line
152       records separated by blank lines. Records can have one of two forms, a
153       specific form and a general form.
154
155       •   The specific form assigns a priority (a "Pin-Priority") to one or
156           more specified packages with a specified version or version range.
157           For example, the following record assigns a high priority to all
158           versions of the perl package whose version number begins with
159           "5.20". Multiple packages can be separated by spaces.
160
161               Package: perl
162               Pin: version 5.20*
163               Pin-Priority: 1001
164
165       •   The general form assigns a priority to all of the package versions
166           in a given distribution (that is, to all the versions of packages
167           that are listed in a certain Release file) or to all of the package
168           versions coming from a particular Internet site, as identified by
169           the site's fully qualified domain name.
170
171           This general-form entry in the APT preferences file applies only to
172           groups of packages. For example, the following record assigns a
173           high priority to all package versions available from the local
174           site.
175
176               Package: *
177               Pin: origin ""
178               Pin-Priority: 999
179
180           A note of caution: the keyword used here is "origin" which can be
181           used to match a hostname. The following record will assign a high
182           priority to all versions available from the server identified by
183           the hostname "ftp.de.debian.org"
184
185               Package: *
186               Pin: origin "ftp.de.debian.org"
187               Pin-Priority: 999
188
189           This should not be confused with the Origin of a distribution as
190           specified in a Release file. What follows the "Origin:" tag in a
191           Release file is not an Internet address but an author or vendor
192           name, such as "Debian" or "Ximian".
193
194           The following record assigns a low priority to all package versions
195           belonging to any distribution whose Archive name is "unstable".
196
197               Package: *
198               Pin: release a=unstable
199               Pin-Priority: 50
200
201           The following record assigns a high priority to all package
202           versions belonging to any distribution whose Codename is
203           "bookworm".
204
205               Package: *
206               Pin: release n=bookworm
207               Pin-Priority: 900
208
209           The following record assigns a high priority to all package
210           versions belonging to any release whose Archive name is "stable"
211           and whose release Version number is "11".
212
213               Package: *
214               Pin: release a=stable, v=11
215               Pin-Priority: 500
216
217       The effect of the comma operator is similar to an "and" in logic: All
218       conditions must be satisfied for the pin to match. There is one
219       exception: For any type of condition (such as two "a" conditions), only
220       the last such condition is checked.
221
222   Regular expressions and glob(7) syntax
223       APT also supports pinning by glob(7) expressions, and regular
224       expressions surrounded by slashes. For example, the following example
225       assigns the priority 500 to all packages from experimental where the
226       name starts with gnome (as a glob(7)-like expression) or contains the
227       word kde (as a POSIX extended regular expression surrounded by
228       slashes).
229
230           Package: gnome* /kde/
231           Pin: release a=experimental
232           Pin-Priority: 500
233
234       The rule for those expressions is that they can occur anywhere where a
235       string can occur. Thus, the following pin assigns the priority 990 to
236       all packages from a release starting with hirsute.
237
238           Package: *
239           Pin: release n=hirsute*
240           Pin-Priority: 990
241
242       If a regular expression occurs in a Package field, the behavior is the
243       same as if this regular expression were replaced with a list of all
244       package names it matches. It is undecided whether this will change in
245       the future; thus you should always list wild-card pins first, so later
246       specific pins override it. The pattern "*" in a Package field is not
247       considered a glob(7) expression in itself.
248
249   Pinning by source package
250       APT supports pinning by source packages. To pin by a source package,
251       prepend "src:" to the package name.
252
253       For example, to pin all binaries produced by the apt source package of
254       this APT's version to 990, you can do:
255
256           Package: src:apt
257           Pin: version 2.3.11
258           Pin-Priority: 990
259
260       Source package pinning can be combined with regular expressions and
261       glob patterns, and can also take a binary architecture.
262
263       For example, let's pin all binaries for all architectures produced by
264       any source package containing apt in its name to 990:
265
266           Package: src:*apt*:any
267           Pin: version *
268           Pin-Priority: 990
269
270   How APT Interprets Priorities
271       Priorities (P) assigned in the APT preferences file must be positive or
272       negative integers. They are interpreted as follows (roughly speaking):
273
274       P >= 1000
275           causes a version to be installed even if this constitutes a
276           downgrade of the package
277
278       990 <= P < 1000
279           causes a version to be installed even if it does not come from the
280           target release, unless the installed version is more recent
281
282       500 <= P < 990
283           causes a version to be installed unless there is a version
284           available belonging to the target release or the installed version
285           is more recent
286
287       100 <= P < 500
288           causes a version to be installed unless there is a version
289           available belonging to some other distribution or the installed
290           version is more recent
291
292       0 < P < 100
293           causes a version to be installed only if there is no installed
294           version of the package
295
296       P < 0
297           prevents the version from being installed
298
299       P = 0
300           has undefined behaviour, do not use it.
301
302       The first specific-form record matching an available package version
303       determines the priority of the package version. Failing that, the
304       priority of the package is defined as the maximum of all priorities
305       defined by generic-form records matching the version. Records defined
306       using patterns in the Pin field other than "*" are treated like
307       specific-form records.
308
309       For example, suppose the APT preferences file contains the three
310       records presented earlier:
311
312           Package: perl
313           Pin: version 5.20*
314           Pin-Priority: 1001
315
316           Package: *
317           Pin: origin ""
318           Pin-Priority: 999
319
320           Package: *
321           Pin: release unstable
322           Pin-Priority: 50
323
324       Then:
325
326       •   The most recent available version of the perl package will be
327           installed, so long as that version's version number begins with
328           "5.20". If any 5.20* version of perl is available and the installed
329           version is 5.24*, then perl will be downgraded.
330
331       •   A version of any package other than perl that is available from the
332           local system has priority over other versions, even versions
333           belonging to the target release.
334
335       •   A version of a package whose origin is not the local system but
336           some other site listed in sources.list(5) and which belongs to an
337           unstable distribution is only installed if it is selected for
338           installation and no version of the package is already installed.
339
340
341   Determination of Package Version and Distribution Properties
342       The locations listed in the sources.list(5) file should provide
343       Packages and Release files to describe the packages available at that
344       location.
345
346       The Packages file is normally found in the directory
347       .../dists/dist-name/component/arch: for example,
348       .../dists/stable/main/binary-i386/Packages. It consists of a series of
349       multi-line records, one for each package available in that directory.
350       Only two lines in each record are relevant for setting APT priorities:
351
352       the Package: line
353           gives the package name
354
355       the Version: line
356           gives the version number for the named package
357
358       The Release file is normally found in the directory
359       .../dists/dist-name: for example, .../dists/stable/Release, or
360       .../dists/bullseye/Release. It consists of a single multi-line record
361       which applies to all of the packages in the directory tree below its
362       parent. Unlike the Packages file, nearly all of the lines in a Release
363       file are relevant for setting APT priorities:
364
365       the Archive: or Suite: line
366           names the archive to which all the packages in the directory tree
367           belong. For example, the line "Archive: stable" or "Suite: stable"
368           specifies that all of the packages in the directory tree below the
369           parent of the Release file are in a stable archive. Specifying this
370           value in the APT preferences file would require the line:
371
372               Pin: release a=stable
373
374       the Codename: line
375           names the codename to which all the packages in the directory tree
376           belong. For example, the line "Codename: bookworm" specifies that
377           all of the packages in the directory tree below the parent of the
378           Release file belong to a version named bookworm. Specifying this
379           value in the APT preferences file would require the line:
380
381               Pin: release n=bookworm
382
383       the Version: line
384           names the release version. For example, the packages in the tree
385           might belong to Debian release version 11. Note that there is
386           normally no version number for the testing and unstable
387           distributions because they have not been released yet. Specifying
388           this in the APT preferences file would require one of the following
389           lines.
390
391               Pin: release v=11
392               Pin: release a=stable, v=11
393               Pin: release 11
394
395       the Component: line
396           names the licensing component associated with the packages in the
397           directory tree of the Release file. For example, the line
398           "Component: main" specifies that all the packages in the directory
399           tree are from the main component, which entails that they are
400           licensed under terms listed in the Debian Free Software Guidelines.
401           Specifying this component in the APT preferences file would require
402           the line:
403
404               Pin: release c=main
405
406       the Origin: line
407           names the originator of the packages in the directory tree of the
408           Release file. Most commonly, this is Debian. Specifying this origin
409           in the APT preferences file would require the line:
410
411               Pin: release o=Debian
412
413       the Label: line
414           names the label of the packages in the directory tree of the
415           Release file. Most commonly, this is Debian. Specifying this label
416           in the APT preferences file would require the line:
417
418               Pin: release l=Debian
419
420       All of the Packages and Release files retrieved from locations listed
421       in the sources.list(5) file are stored in the directory
422       /var/lib/apt/lists, or in the file named by the variable
423       Dir::State::Lists in the apt.conf file. For example, the file
424       debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release
425       contains the Release file retrieved from the site debian.lcs.mit.edu
426       for binary-i386 architecture files from the contrib component of the
427       unstable distribution.
428
429   Optional Lines in an APT Preferences Record
430       Each record in the APT preferences file can optionally begin with one
431       or more lines beginning with the word Explanation:. This provides a
432       place for comments.
433

EXAMPLES

435   Tracking Stable
436       The following APT preferences file will cause APT to assign a priority
437       higher than the default (500) to all package versions belonging to a
438       stable distribution and a prohibitively low priority to package
439       versions belonging to other Debian distributions.
440
441           Explanation: Uninstall or do not install any Debian-originated
442           Explanation: package versions other than those in the stable distro
443           Package: *
444           Pin: release a=stable
445           Pin-Priority: 900
446
447           Package: *
448           Pin: release o=Debian
449           Pin-Priority: -10
450
451       With a suitable sources.list(5) file and the above preferences file,
452       any of the following commands will cause APT to upgrade to the latest
453       stable version(s).
454
455           apt-get install package-name
456           apt-get upgrade
457           apt-get dist-upgrade
458
459       The following command will cause APT to upgrade the specified package
460       to the latest version from the testing distribution; the package will
461       not be upgraded again unless this command is given again.
462
463           apt-get install package/testing
464
465
466   Tracking Testing or Unstable
467       The following APT preferences file will cause APT to assign a high
468       priority to package versions from the testing distribution, a lower
469       priority to package versions from the unstable distribution, and a
470       prohibitively low priority to package versions from other Debian
471       distributions.
472
473           Package: *
474           Pin: release a=testing
475           Pin-Priority: 900
476
477           Package: *
478           Pin: release a=unstable
479           Pin-Priority: 800
480
481           Package: *
482           Pin: release o=Debian
483           Pin-Priority: -10
484
485       With a suitable sources.list(5) file and the above preferences file,
486       any of the following commands will cause APT to upgrade to the latest
487       testing version(s).
488
489           apt-get install package-name
490           apt-get upgrade
491           apt-get dist-upgrade
492
493       The following command will cause APT to upgrade the specified package
494       to the latest version from the unstable distribution. Thereafter,
495       apt-get upgrade will upgrade the package to the most recent testing
496       version if that is more recent than the installed version, otherwise,
497       to the most recent unstable version if that is more recent than the
498       installed version.
499
500           apt-get install package/unstable
501
502
503   Tracking the evolution of a codename release
504       The following APT preferences file will cause APT to assign a priority
505       higher than the default (500) to all package versions belonging to a
506       specified codename of a distribution and a prohibitively low priority
507       to package versions belonging to other Debian distributions, codenames
508       and archives. Note that with this APT preference APT will follow the
509       migration of a release from the archive testing to stable and later
510       oldstable. If you want to follow for example the progress in testing
511       notwithstanding the codename changes you should use the example
512       configurations above.
513
514           Explanation: Uninstall or do not install any Debian-originated package versions
515           Explanation: other than those in the distribution codenamed with bookworm or sid
516           Package: *
517           Pin: release n=bookworm
518           Pin-Priority: 900
519
520           Explanation: Debian unstable is always codenamed with sid
521           Package: *
522           Pin: release n=sid
523           Pin-Priority: 800
524
525           Package: *
526           Pin: release o=Debian
527           Pin-Priority: -10
528
529       With a suitable sources.list(5) file and the above preferences file,
530       any of the following commands will cause APT to upgrade to the latest
531       version(s) in the release codenamed with bookworm.
532
533           apt-get install package-name
534           apt-get upgrade
535           apt-get dist-upgrade
536
537       The following command will cause APT to upgrade the specified package
538       to the latest version from the sid distribution. Thereafter, apt-get
539       upgrade will upgrade the package to the most recent bookworm version if
540       that is more recent than the installed version, otherwise, to the most
541       recent sid version if that is more recent than the installed version.
542
543           apt-get install package/sid
544
545

FILES

547       /etc/apt/preferences
548           Version preferences file. This is where you would specify
549           "pinning", i.e. a preference to get certain packages from a
550           separate source or from a different version of a distribution.
551           Configuration Item: Dir::Etc::Preferences.
552
553       /etc/apt/preferences.d/
554           File fragments for the version preferences. Configuration Item:
555           Dir::Etc::PreferencesParts.
556

SEE ALSO

558       apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)
559

BUGS

561       APT bug page[1]. If you wish to report a bug in APT, please see
562       /usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command.
563

AUTHOR

565       APT team
566

NOTES

568        1. APT bug page
569           http://bugs.debian.org/src:apt
570
571
572
573APT 2.3.11                      10 August 2020              APT_PREFERENCES(5)
Impressum