1APT_PREFERENCES(5) APT_PREFERENCES(5)
2
6 apt_preferences - Preference control file for APT
7
9 The APT preferences file /etc/apt/preferences can be used to control
10 which versions of packages will be selected for installation.
11 Several versions of a package may be available for installation when
13 the sources.list(5) file contains references to more than one distribu‐
14 tion (for example, stable and testing). APT assigns a priority to each
15 version that is available. Subject to dependency constraints, apt-get
16 selects the version with the highest priority for installation. The
17 APT preferences file overrides the priorities that APT assigns to pack‐
18 age versions by default, thus giving the user control over which one is
19 selected for installation.
20 Several instances of the same version of a package may be available
22 when the sources.list(5) file contains references to more than one
23 source. In this case apt-get downloads the instance listed earliest in
24 the sources.list(5) file. The APT preferences file does not affect the
25 choice of instance, only the choice of version.
26 APT'S DEFAULT PRIORITY ASSIGNMENTS
28 If there is no preferences file or if there is no entry in the file
29 that applies to a particular version then the priority assigned to that
30 version is the priority of the distribution to which that version
31 belongs. It is possible to single out a distribution, "the target
32 release", which receives a higher priority than other distributions do
33 by default. The target release can be set on the apt-get command line
34 or in the APT configuration file /etc/apt/apt.conf. For example,
35 apt-get install -t testing some-package
37 APT::Default-Release "stable";
39 If the target release has been specified then APT uses the following
41 algorithm to set the priorities of the versions of a package. Assign:
42 priority 100
44 to the version that is already installed (if any).
45 priority 500
47 to the versions that are not installed and do not belong to the
48 target release.
49 priority 990
51 to the versions that are not installed and belong to the target
52 release.
53 If the target release has not been specified then APT simply assigns
55 priority 100 to all installed package versions and priority 500 to all
56 uninstalled package versions.
57 APT then applies the following rules, listed in order of precedence, to
59 determine which version of a package to install.
60 · Never downgrade unless the priority of an available version exceeds
62 1000. ("Downgrading" is installing a less recent version of a pack‐
63 age in place of a more recent version. Note that none of APT's
64 default priorities exceeds 1000; such high priorities can only be set
65 in the preferences file. Note also that downgrading a package can be
66 risky.)
67 · Install the highest priority version.
69 · If two or more versions have the same priority, install the most
71 recent one (that is, the one with the higher version number).
72 · If two or more versions have the same priority and version number but
74 either the packages differ in some of their metadata or the --rein‐
75 stall option is given, install the uninstalled one.
76 In a typical situation, the installed version of a package (priority
78 100) is not as recent as one of the versions available from the sources
79 listed in the sources.list(5) file (priority 500 or 990). Then the
80 package will be upgraded when apt-get install some-package or apt-get
81 upgrade is executed.
82 More rarely, the installed version of a package is more recent than any
84 of the other available versions. The package will not be downgraded
85 when apt-get install some-package or apt-get upgrade is executed.
86 Sometimes the installed version of a package is more recent than the
88 version belonging to the target release, but not as recent as a version
89 belonging to some other distribution. Such a package will indeed be
90 upgraded when apt-get install some-package or apt-get upgrade is exe‐
91 cuted, because at least one of the available versions has a higher pri‐
92 ority than the installed version.
93 THE EFFECT OF APT PREFERENCES
95 The APT preferences file allows the system administrator to control the
96 assignment of priorities. The file consists of one or more multi-line
97 records separated by blank lines. Records can have one of two forms, a
98 specific form and a general form.
99 · The specific form assigns a priority (a "Pin-Priority") to a speci‐
101 fied package and specified version or version range. For example,
102 the following record assigns a high priority to all versions of the
103 perl package whose version number begins with "5.8".
104 Package: perl
106 Pin: version 5.8*
107 Pin-Priority: 1001
108 · The general form assigns a priority to all of the package versions in
110 a given distribution (that is, to all the versions of packages that
111 are listed in a certain Release file) or to all of the package ver‐
112 sions coming from a particular Internet site, as identified by the
113 site's fully qualified domain name.
114 This general-form entry in the APT preferences file applies only to
116 groups of packages. For example, the following record assigns a high
117 priority to all package versions available from the local site.
118 Package: *
120 Pin: origin ""
121 Pin-Priority: 999
122 A note of caution: the keyword used here is "origin". This should
124 not be confused with the Origin of a distribution as specified in a
125 Release file. What follows the "Origin:" tag in a Release file is
126 not an Internet address but an author or vendor name, such as
127 "Debian" or "Ximian".
128 The following record assigns a low priority to all package versions
130 belonging to any distribution whose Archive name is "unstable".
131 Package: *
133 Pin: release a=unstable
134 Pin-Priority: 50
135 The following record assigns a high priority to all package versions
137 belonging to any release whose Archive name is "stable" and whose
138 release Version number is "3.0".
139 Package: *
141 Pin: release a=unstable, v=3.0
142 Pin-Priority: 50
143 HOW APT INTERPRETS PRIORITIES
145 Priorities (P) assigned in the APT preferences file must be positive or
146 negative integers. They are interpreted as follows (roughly speaking):
147 P > 1000
149 causes a version to be installed even if this constitutes a
150 downgrade of the package
151 990 < P <=1000
153 causes a version to be installed even if it does not come from
154 the target release, unless the installed version is more recent
155 500 < P <=990
157 causes a version to be installed unless there is a version
158 available belonging to the target release or the installed ver‐
159 sion is more recent
160 100 < P <=500
162 causes a version to be installed unless there is a version
163 available belonging to some other distribution or the installed
164 version is more recent
165 0 < P <=100
167 causes a version to be installed only if there is no installed
168 version of the package
169 P < 0 prevents the version from being installed
171 If any specific-form records match an available package version then
173 the first such record determines the priority of the package version.
174 Failing that, if any general-form records match an available package
175 version then the first such record determines the priority of the pack‐
176 age version.
177 For example, suppose the APT preferences file contains the three
179 records presented earlier:
180 Package: perl
182 Pin: version 5.8*
183 Pin-Priority: 1001
184 Package: *
186 Pin: origin ""
187 Pin-Priority: 999
188 Package: *
190 Pin: release unstable
191 Pin-Priority: 50
192 Then:
193 · The most recent available version of the perl package will be
195 installed, so long as that version's version number begins with
196 "5.8". If any 5.8* version of perl is available and the installed
197 version is 5.9*, then perl will be downgraded.
198 · A version of any package other than perl that is available from the
200 local system has priority over other versions, even versions belong‐
201 ing to the target release.
202 · A version of a package whose origin is not the local system but some
204 other site listed in sources.list(5) and which belongs to an unstable
205 distribution is only installed if it is selected for installation and
206 no version of the package is already installed.
207 DETERMINATION OF PACKAGE VERSION AND DISTRIBUTION PROPERTIES
209 The locations listed in the sources.list(5) file should provide Pack‐
210 ages and Release files to describe the packages available at that loca‐
211 tion.
212 The Packages file is normally found in the directory .../dists/dist-
214 name/component/arch: for example, .../dists/stable/main/binary-
215 i386/Packages. It consists of a series of multi-line records, one for
216 each package available in that directory. Only two lines in each
217 record are relevant for setting APT priorities:
218 the Package: line
220 gives the package name
221 the Version: line
223 gives the version number for the named package
224 The Release file is normally found in the directory .../dists/dist-
226 name: for example, .../dists/stable/Release, or
227 .../dists/woody/Release. It consists of a single multi-line record
228 which applies to all of the packages in the directory tree below its
229 parent. Unlike the Packages file, nearly all of the lines in a Release
230 file are relevant for setting APT priorities:
231 the Archive: line
233 names the archive to which all the packages in the directory
234 tree belong. For example, the line "Archive: stable" specifies
235 that all of the packages in the directory tree below the parent
236 of the Release file are in a stable archive. Specifying this
237 value in the APT preferences file would require the line:
238 Pin: release a=stable
240 the Version: line
242 names the release version. For example, the packages in the
243 tree might belong to Debian GNU/Linux release version 3.0. Note
244 that there is normally no version number for the testing and
245 unstable distributions because they have not been released yet.
246 Specifying this in the APT preferences file would require one of
247 the following lines.
248 Pin: release v=3.0
250 Pin: release a=stable, v=3.0
251 Pin: release 3.0
252 the Component: line
254 names the licensing component associated with the packages in
255 the directory tree of the Release file. For example, the line
256 "Component: main" specifies that all the packages in the direc‐
257 tory tree are from the main component, which entails that they
258 are licensed under terms listed in the Debian Free Software
259 Guidelines. Specifying this component in the APT preferences
260 file would require the line:
261 Pin: release c=main
263 the Origin: line
265 names the originator of the packages in the directory tree of
266 the Release file. Most commonly, this is Debian. Specifying
267 this origin in the APT preferences file would require the line:
268 Pin: release o=Debian
270 the Label: line
272 names the label of the packages in the directory tree of the
273 Release file. Most commonly, this is Debian. Specifying this
274 label in the APT preferences file would require the line:
275 Pin: release l=Debian
277 All of the Packages and Release files retrieved from locations listed
279 in the sources.list(5) file are stored in the directory
280 /var/lib/apt/lists, or in the file named by the variable
281 Dir::State::Lists in the apt.conf file. For example, the file
282 debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release
283 contains the Release file retrieved from the site debian.lcs.mit.edu
284 for binary-i386 architecture files from the contrib component of the
285 unstable distribution.
286 OPTIONAL LINES IN AN APT PREFERENCES RECORD
288 Each record in the APT preferences file can optionally begin with one
289 or more lines beginning with the word Explanation:. This provides a
290 place for comments.
291 The Pin-Priority: line in each APT preferences record is optional. If
293 omitted, APT assigs a priority of 1 less than the last value specified
294 on a line beginning with Pin-Priority: release ....
295
297 TRACKING STABLE
298 The following APT preferences file will cause APT to assign a priority
299 higher than the default (500) to all package versions belonging to a
300 stable distribution and a prohibitively low priority to package ver‐
301 sions belonging to other Debian distributions.
302 Explanation: Uninstall or do not install any Debian-originated
304 Explanation: package versions other than those in the stable distro
305 Package: *
306 Pin: release a=stable
307 Pin-Priority: 900
308 Package: *
310 Pin: release o=Debian
311 Pin-Priority: -10
312 With a suitable sources.list(5) file and the above preferences file,
314 any of the following commands will cause APT to upgrade to the latest
315 stable version(s).
316 apt-get install package-name
318 apt-get upgrade
319 apt-get dist-upgrade
320 The following command will cause APT to upgrade the specified package
322 to the latest version from the testing distribution; the package will
323 not be upgraded again unless this command is given again.
324 apt-get install package/testing
326 TRACKING TESTING OR UNSTABLE
328 The following APT preferences file will cause APT to assign a high pri‐
329 ority to package versions from the testing distribution, a lower prior‐
330 ity to package versions from the unstable distribution, and a prohibi‐
331 tively low priority to package versions from other Debian distribu‐
332 tions.
333 Package: *
335 Pin: release a=testing
336 Pin-Priority: 900
337 Package: *
339 Pin: release a=unstable
340 Pin-Priority: 800
341 Package: *
343 Pin: release o=Debian
344 Pin-Priority: -10
345 With a suitable sources.list(5) file and the above preferences file,
347 any of the following commands will cause APT to upgrade to the latest
348 testing version(s).
349 apt-get install package-name
351 apt-get upgrade
352 apt-get dist-upgrade
353 The following command will cause APT to upgrade the specified package
355 to the latest version from the unstable distribution. Thereafter, apt-
356 get upgrade will upgrade the package to the most recent testing version
357 if that is more recent than the installed version, otherwise, to the
358 most recent unstable version if that is more recent than the installed
359 version.
360 apt-get install package/unstable
362
364 apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)
365
367 See the APT bug page <URL:http://bugs.debian.org/src:apt>. If you wish
368 to report a bug in APT, please see /usr/share/doc/debian/bug-report‐
369 ing.txt or the reportbug(1) command.
370
372 APT was written by the APT team <apt@packages.debian.org>.
373 02 August 2007 APT_PREFERENCES(5)