1APT_PREFERENCES(5) apt_preferences APT_PREFERENCES(5)
3
7 apt_preferences - Preference control file for APT
8
11 The APT preferences file /etc/apt/preferences can be used to control
12 which versions of packages will be selected for installation.
13 Several versions of a package may be available for installation when
15 the sources.list(5) file contains references to more than one distribu‐
16 tion (for example, stable and testing). APT assigns a priority to each
17 version that is available. Subject to dependency constraints, apt-
18 get(8) selects the version with the highest priority for installation.
19 The APT preferences file overrides the priorities that APT assigns to
20 package versions by default, thus giving the user control over which
21 one is selected for installation.
22 Several instances of the same version of a package may be available
24 when the sources.list(5) file contains references to more than one
25 source. In this case apt-get(8) downloads the instance listed earliest
26 in the sources.list(5) file. The APT preferences file does not affect
27 the choice of instance, only the choice of version.
28
31 If there is no preferences file or if there is no entry in the file
32 that applies to a particular version then the priority assigned to that
33 version is the priority of the distribution to which that version
34 belongs. It is possible to single out a distribution, "the target
35 release", which receives a higher priority than other distributions do
36 by default. The target release can be set on the apt-get(8) command
37 line or in the APT configuration file /etc/apt/apt.conf(5). For exam‐
38 ple,
39 apt-get install -t testing some-package
41 To configure the default release in the configuration file, use:
43 APT::Default-Release "stable";
45 If the target release has been specified then APT uses the following
47 algorithm to set the priorities of the versions of a package. Assign:
48 priority 100
50 to the version that is already installed (if any).
51 priority 500
53 to the versions that are not installed and do not belong to the
54 target release.
55 priority 990
57 to the versions that are not installed and belong to the target
58 release.
59 If the target release has not been specified then APT simply assigns
61 priority 100 to all installed package versions and priority 500 to all
62 uninstalled package versions.
63 APT then applies the following rules, listed in order of precedence, to
65 determine which version of a package to install:
66 · Never downgrade unless the priority of an available version exceeds
68 1000. ("Downgrading" is installing a less recent version of a pack‐
69 age in place of a more recent version. Note that none of APT's
70 default priorities exceeds 1000; such high priorities can only be set
71 in the preferences file. Note also that downgrading a package can be
72 risky.)
73 · Install the highest priority version.
75 · If two or more versions have the same priority, install the most
77 recent one (that is, the one with the higher version number).
78 · If two or more versions have the same priority and version number but
80 either the packages differ in some of their metadata or the --rein‐
81 stall option is given, install the uninstalled one.
82 In a typical situation, the installed version of a package (priority
84 100) is not as recent as one of the versions available from the sources
85 listed in the sources.list(5) file (priority 500 or 990). Then the
86 package will be upgraded when apt-get install some-package or apt-get
87 upgrade is executed.
88 More rarely, the installed version of a package is more recent than any
90 of the other available versions. The package will not be downgraded
91 when apt-get install some-package or apt-get upgrade is executed.
92 Sometimes the installed version of a package is more recent than the
94 version belonging to the target release, but not as recent as a version
95 belonging to some other distribution. Such a package will indeed be
96 upgraded when apt-get install some-package or apt-get upgrade is exe‐
97 cuted, because at least one of the available versions has a higher pri‐
98 ority than the installed version.
99
102 The APT preferences file allows the system administrator to control the
103 assignment of priorities. The file consists of one or more multi-line
104 records separated by blank lines. Records can have one of two forms, a
105 specific form and a general form.
106 · The specific form assigns a priority (a "Pin-Priority") to a speci‐
108 fied package and specified version or version range. For example,
109 the following record assigns a high priority to all versions of the
110 perl package whose version number begins with "5.8".
111 Package: perl
113 Pin: version 5.8*
114 Pin-Priority: 1001
115 · The general form assigns a priority to all of the package versions in
117 a given distribution (that is, to all the versions of packages that
118 are listed in a certain Release file) or to all of the package ver‐
119 sions coming from a particular Internet site, as identified by the
120 site's fully qualified domain name.
121 This general-form entry in the APT preferences file applies only to
123 groups of packages. For example, the following record assigns a high
124 priority to all package versions available from the local site.
125 Package: *
127 Pin: origin ""
128 Pin-Priority: 999
129 A note of caution: the keyword used here is "origin". This should not
131 be confused with the Origin of a distribution as specified in a
132 Release file. What follows the "Origin:" tag in a Release file is
133 not an Internet address but an author or vendor name, such as
134 "Debian" or "Ximian".
135 The following record assigns a low priority to all package versions
137 belonging to any distribution whose Archive name is "unstable".
138 Package: *
140 Pin: release a=unstable
141 Pin-Priority: 50
142 The following record assigns a high priority to all package versions
144 belonging to any release whose Archive name is "stable" and whose
145 release Version number is "3.0".
146 Package: *
148 Pin: release a=unstable, v=3.0
149 Pin-Priority: 50
150
153 Priorities (P) assigned in the APT preferences file must be positive or
154 negative integers. They are interpreted as follows (roughly speaking):
155 P > 1000
157 causes a version to be installed even if this constitutes a
158 downgrade of the package.
159 990 < P <=1000
161 causes a version to be installed even if it does not come from
162 the target release, unless the installed version is more recent.
163 500 < P <=990
165 causes a version to be installed unless there is a version
166 available belonging to the target release or the installed ver‐
167 sion is more recent.
168 100 < P <=500
170 causes a version to be installed unless there is a version
171 available belonging to some other distribution or the installed
172 version is more recent.
173 0 < P <=100
175 causes a version to be installed only if there is no installed
176 version of the package.
177 P < 0 prevents the version from being installed.
179 If any specific-form records match an available package version then
181 the first such record determines the priority of the package version.
182 Failing that, if any general-form records match an available package
183 version then the first such record determines the priority of the pack‐
184 age version.
185 For example, suppose the APT preferences file contains the three
187 records presented earlier:
188 Package: perl
190 Pin: version 5.8*
191 Pin-Priority: 1001
192 Package: *
194 Pin: origin ""
195 Pin-Priority: 999
196 Package: *
198 Pin: release unstable
199 Pin-Priority: 50
200 Then:
202 · The most recent available version of the perl package will be
204 installed, so long as that version's version number begins with
205 "5.8". If any 5.8* version of perl is available and the installed
206 version is 5.9*, then perl will be downgraded.
207 · A version of any package other than perl that is available from the
209 local system has priority over other versions, even versions belong‐
210 ing to the target release.
211 · A version of a package whose origin is not the local system but some
213 other site listed in sources.list(5) and which belongs to an unstable
214 distribution is only installed if it is selected for installation and
215 no version of the package is already installed.
216
219 The locations listed in the sources.list(5) file should provide Pack‐
220 ages and Release files to describe the packages available at that loca‐
221 tion.
222 The Packages File
224 The Packages file is normally found in the directory .../dists/dist-
226 name/component/arch. For example: .../dists/stable/main/binary-
227 i386/Packages. It consists of a series of multi-line records, one for
228 each package available in that directory. Only two lines in each
229 record are relevant for setting APT priorities:
230 Package:
232 this line gives the package name.
233 Version:
235 this line gives the version number for the named package.
236 The Release File
238 The Release file is normally found in the directory .../dists/dist-
240 name. For example: .../dists/stable/Release, or
241 .../dists/woody/Release. It consists of a single multi-line record
242 which applies to all of the packages in the directory tree below its
243 parent. Unlike the Packages file, nearly all of the lines in a Release
244 file are relevant for setting APT priorities:
245 Archive:
247 this line names the archive to which all the packages in the
248 directory tree belong. For example, the line "Archive: stable"
249 specifies that all of the packages in the directory tree below
250 the parent of the Release file are in a stable archive. Speci‐
251 fying this value in the APT preferences file would require the
252 line:
253 Pin: release a=stable
255 Version:
257 this line names the release version. For example, the packages
258 in the tree might belong to Debian GNU/Linux release version
259 3.0. Note that there is normally no version number for the
260 testing and unstable distributions because they have not been
261 released yet. Specifying this in the APT preferences file would
262 require one of the following lines.
263 Pin: release v=3.0
265 Pin: release a=stable, v=3.0
266 Pin: release 3.0
267 Component:
269 this line names the licensing component associated with the
270 packages in the directory tree of the Release file. For example,
271 the line "Component: main" specifies that all the packages in
272 the directory tree are from the main component, which entails
273 that they are licensed under terms listed in the Debian Free
274 Software Guidelines. Specifying this component in the APT pref‐
275 erences file would require the line:
276 Pin: release c=main
278 Origin:
280 this line names the originator of the packages in the directory
281 tree of the Release file. Most commonly, this is Debian. Spec‐
282 ifying this origin in the APT preferences file would require the
283 line:
284 Pin: release o=Debian
286 Label: this line names the label of the packages in the directory tree
288 of the Release file. Most commonly, this is Debian. Specifying
289 this label in the APT preferences file would require the line:
290 Pin: release l=Debian
292 All of the Packages and Release files retrieved from locations listed
294 in the sources.list(5) file are stored in the directory
295 /var/lib/apt/lists, or in the file named by the variable
296 Dir::State::Lists in the apt.conf(5) file. For example, the file
297 debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release
298 contains the Release file retrieved from the site debian.lcs.mit.edu
299 for binary-i386 architecture files from the contrib component of the
300 unstable distribution.
301
304 Each record in the APT preferences file can optionally begin with one
305 or more lines beginning with the word Explanation:. This provides a
306 place for comments.
307 The Pin-Priority: line in each APT preferences record is optional. If
309 omitted, APT assigs a priority of 1 less than the last value specified
310 on a previous line beginning with Pin-Priority: release ....
311
314 The following examples make use of the component names "stable", "test‐
315 ing", and "unstable", but these are obviously defined by the vendor and
316 are determined by the repository layout.
317 Tracking a "STABLE" distribution
319 The following APT preferences file will cause APT to assign a priority
321 higher than the default (500) to all package versions belonging to a
322 "stable" distribution and a prohibitively low priority to package ver‐
323 sions belonging to other distributions.
324 Explanation: Uninstall or do not install any Debian-originated
326 Explanation: package versions other than those in the stable distro
327 Package: *
328 Pin: release a=stable
329 Pin-Priority: 900
330 Package: *
332 Pin: release o=Debian
333 Pin-Priority: -10
334 With a suitable sources.list(5) file and the above preferences file,
336 any of the following commands will cause APT to upgrade to the latest
337 stable version(s):
338 apt-get install package-name
340 apt-get upgrade
341 apt-get dist-upgrade
342 The following command will cause APT to upgrade the specified package
344 ("package") to the latest version from the "testing" distribution; the
345 package will not be upgraded again unless this command is given again.
346 apt-get install package/testing
348 Tracking a "TESTING" or "UNSTABLE" distribution
350 The following APT preferences file will cause APT to assign a high pri‐
352 ority to package versions from the testing distribution, a lower prior‐
353 ity to package versions from the unstable distribution, and a prohibi‐
354 tively low priority to package versions from other Debian distribu‐
355 tions.
356 Package: *
358 Pin: release a=testing
359 Pin-Priority: 900
360 Package: *
362 Pin: release a=unstable
363 Pin-Priority: 800
364 Package: *
366 Pin: release o=Debian
367 Pin-Priority: -10
368 With a suitable sources.list(5) file and the above preferences file,
370 any of the following commands will cause APT to upgrade to the latest
371 testing version(s):
372 apt-get install package-name
374 apt-get upgrade
375 apt-get dist-upgrade
376 The following command will cause APT to upgrade the specified package
378 to the latest version from the "unstable" distribution. Thereafter,
379 apt-get upgrade will upgrade the package to the most recent "testing"
380 version if that is more recent than the installed version, otherwise to
381 the most recent "unstable" version if that is more recent than the
382 installed version.
383 apt-get install package/unstable
385
388 apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)
389
392 Reporting bugs in APT-RPM is best done in the APT-RPM mailinglist at
393 http://apt-rpm.org/mailinglist.shtml.
394
397 Maintainer and contributor information can be found in the credits page
398 http://apt-rpm.org/about.shtml of APT-RPM.
399APT-RPM 14 Jun 2006 APT_PREFERENCES(5)