- only build documentation in maintainer-mode, include prebuilt manuals
[apt.git] / doc / apt_preferences.5
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document.  This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "APT_PREFERENCES" "5" "29 May 2006" "" ""
7
8 .SH NAME
9 apt_preferences \- Preference control file for APT
10 .SH "DESCRIPTION"
11 .PP
12 The APT preferences file \fI/etc/apt/preferences\fR
13 can be used to control which versions of packages will be selected
14 for installation.
15 .PP
16 Several versions of a package may be available for installation when
17 the \fB\fIsources.list\fB\fR(5) file contains references to more than one distribution
18 (for example, stable and testing).
19 APT assigns a priority to each version that is available.
20 Subject to dependency constraints, \fBapt-get\fR selects the
21 version with the highest priority for installation.
22 The APT preferences file overrides the priorities that APT assigns to
23 package versions by default, thus giving the user control over which
24 one is selected for installation.
25 .PP
26 Several instances of the same version of a package may be available when
27 the \fB\fIsources.list\fB\fR(5) file contains references to more than one source.
28 In this case \fBapt-get\fR downloads the instance listed
29 earliest in the \fB\fIsources.list\fB\fR(5) file.
30 The APT preferences file does not affect the choice of instance, only
31 the choice of version.
32 .SS "APT'S DEFAULT PRIORITY ASSIGNMENTS"
33 .PP
34 If there is no preferences file or if there is no entry in the file
35 that applies to a particular version then the priority assigned to that
36 version is the priority of the distribution to which that version
37 belongs.  It is possible to single out a distribution, "the target release",
38 which receives a higher priority than other distributions do by default.
39 The target release can be set on the \fBapt-get\fR command
40 line or in the APT configuration file \fI/etc/apt/apt.conf\fR\&.
41 For example,
42
43 .nf
44 \fBapt-get install -t testing \fIsome-package\fB\fR
45 .fi
46
47 .nf
48 APT::Default-Release "stable";
49 .fi
50 .PP
51 If the target release has been specified then APT uses the following
52 algorithm to set the priorities of the versions of a package.  Assign:
53 .TP
54 \fBpriority 100\fR
55 to the version that is already installed (if any).
56 .TP
57 \fBpriority 500\fR
58 to the versions that are not installed and do not belong to the target release.
59 .TP
60 \fBpriority 990\fR
61 to the versions that are not installed and belong to the target release.
62 .PP
63 If the target release has not been specified then APT simply assigns
64 priority 100 to all installed package versions and priority 500 to all
65 uninstalled package versions.
66 .PP
67 APT then applies the following rules, listed in order of precedence,
68 to determine which version of a package to install.
69 .TP 0.2i
70 \(bu
71 Never downgrade unless the priority of an available
72 version exceeds 1000.  ("Downgrading" is installing a less recent version
73 of a package in place of a more recent version.  Note that none of APT's
74 default priorities exceeds 1000; such high priorities can only be set in
75 the preferences file.  Note also that downgrading a package
76 can be risky.)
77 .TP 0.2i
78 \(bu
79 Install the highest priority version.
80 .TP 0.2i
81 \(bu
82 If two or more versions have the same priority,
83 install the most recent one (that is, the one with the higher version
84 number).
85 .TP 0.2i
86 \(bu
87 If two or more versions have the same priority and
88 version number but either the packages differ in some of their metadata or the
89 --reinstall option is given, install the uninstalled one.
90 .PP
91 In a typical situation, the installed version of a package (priority 100)
92 is not as recent as one of the versions available from the sources listed in
93 the \fB\fIsources.list\fB\fR(5) file (priority 500 or 990).  Then the package will be upgraded
94 when \fBapt-get install \fIsome-package\fB\fR
95 or \fBapt-get upgrade\fR is executed.
96 .PP
97 More rarely, the installed version of a package is \fBmore\fR recent
98 than any of the other available versions.  The package will not be downgraded
99 when \fBapt-get install \fIsome-package\fB\fR
100 or \fBapt-get upgrade\fR is executed.
101 .PP
102 Sometimes the installed version of a package is more recent than the
103 version belonging to the target release, but not as recent as a version
104 belonging to some other distribution.  Such a package will indeed be upgraded
105 when \fBapt-get install \fIsome-package\fB\fR
106 or \fBapt-get upgrade\fR is executed,
107 because at least \fBone\fR of the available versions has a higher
108 priority than the installed version.
109 .SS "THE EFFECT OF APT PREFERENCES"
110 .PP
111 The APT preferences file allows the system administrator to control the
112 assignment of priorities.  The file consists of one or more multi-line records
113 separated by blank lines.  Records can have one of two forms, a specific form
114 and a general form.
115 .TP 0.2i
116 \(bu
117 The specific form assigns a priority (a "Pin-Priority") to a
118 specified package and specified version or version range.  For example,
119 the following record assigns a high priority to all versions of
120 the \fIperl\fR package whose version number begins with "5.8".
121
122 .nf
123 Package: perl
124 Pin: version 5.8*
125 Pin-Priority: 1001
126 .fi
127 .TP 0.2i
128 \(bu
129 The general form assigns a priority to all of the package versions in a
130 given distribution (that is, to all the versions of packages that are
131 listed in a certain \fIRelease\fR file) or to all of the package
132 versions coming from a particular Internet site, as identified by the
133 site's fully qualified domain name.
134
135 This general-form entry in the APT preferences file applies only
136 to groups of packages.  For example, the following record assigns a high
137 priority to all package versions available from the local site.
138
139 .nf
140 Package: *
141 Pin: origin ""
142 Pin-Priority: 999
143 .fi
144
145 A note of caution: the keyword used here is "origin".
146 This should not be confused with the Origin of a distribution as
147 specified in a \fIRelease\fR file.  What follows the "Origin:" tag
148 in a \fIRelease\fR file is not an Internet address
149 but an author or vendor name, such as "Debian" or "Ximian".
150
151 The following record assigns a low priority to all package versions
152 belonging to any distribution whose Archive name is "unstable".
153
154 .nf
155 Package: *
156 Pin: release a=unstable
157 Pin-Priority: 50
158 .fi
159
160 The following record assigns a high priority to all package versions
161 belonging to any release whose Archive name is "stable"
162 and whose release Version number is "3.0".
163
164 .nf
165 Package: *
166 Pin: release a=unstable, v=3.0
167 Pin-Priority: 50
168 .fi
169 .SS "HOW APT INTERPRETS PRIORITIES"
170 .PP
171 Priorities (P) assigned in the APT preferences file must be positive
172 or negative integers.  They are interpreted as follows (roughly speaking):
173 .TP
174 \fBP > 1000\fR
175 causes a version to be installed even if this
176 constitutes a downgrade of the package
177 .TP
178 \fB990 < P <=1000\fR
179 causes a version to be installed
180 even if it does not come from the target release,
181 unless the installed version is more recent
182 .TP
183 \fB500 < P <=990\fR
184 causes a version to be installed
185 unless there is a version available belonging to the target release
186 or the installed version is more recent
187 .TP
188 \fB100 < P <=500\fR
189 causes a version to be installed
190 unless there is a version available belonging to some other
191 distribution or the installed version is more recent
192 .TP
193 \fB0 < P <=100\fR
194 causes a version to be installed
195 only if there is no installed version of the package
196 .TP
197 \fBP < 0\fR
198 prevents the version from being installed
199 .PP
200 If any specific-form records match an available package version then the
201 first such record determines the priority of the package version.  
202 Failing that,
203 if any general-form records match an available package version then the
204 first such record determines the priority of the package version.  
205 .PP
206 For example, suppose the APT preferences file contains the three
207 records presented earlier:
208
209 .nf
210 Package: perl
211 Pin: version 5.8*
212 Pin-Priority: 1001
213
214 Package: *
215 Pin: origin ""
216 Pin-Priority: 999
217
218 Package: *
219 Pin: release unstable
220 Pin-Priority: 50
221 .fi
222 Then:
223 .TP 0.2i
224 \(bu
225 The most recent available version of the perl
226 package will be installed, so long as that version's version number begins
227 with "5.8".  If \fBany\fR 5.8* version of perl is
228 available and the installed version is 5.9*, then perl will be
229 downgraded.
230 .TP 0.2i
231 \(bu
232 A version of any package other than perl
233 that is available from the local system has priority over other versions,
234 even versions belonging to the target release.
235 .TP 0.2i
236 \(bu
237 A version of a package whose origin is not the local
238 system but some other site listed in \fB\fIsources.list\fB\fR(5) and which belongs to
239 an unstable distribution is only installed if it is selected
240 for installation and no version of the package is already installed.
241 .SS "DETERMINATION OF PACKAGE VERSION AND DISTRIBUTION PROPERTIES"
242 .PP
243 The locations listed in the \fB\fIsources.list\fB\fR(5) file should provide
244 \fIPackages\fR and \fIRelease\fR files
245 to describe the packages available at that location.
246 .PP
247 The \fIPackages\fR file is normally found in the directory
248 \fI\&.../dists/dist-name/component/arch\fR:
249 for example, \fI\&.../dists/stable/main/binary-i386/Packages\fR\&.
250 It consists of a series of multi-line records, one for each package available
251 in that directory.  Only two lines in each record are relevant for setting
252 APT priorities:
253 .TP
254 \fBthe Package: line\fR
255 gives the package name
256 .TP
257 \fBthe Version: line\fR
258 gives the version number for the named package
259 .PP
260 The \fIRelease\fR file is normally found in the directory
261 \fI\&.../dists/dist-name\fR:
262 for example, \fI\&.../dists/stable/Release\fR,
263 or \fI\&.../dists/woody/Release\fR\&.
264 It consists of a single multi-line record which applies to \fBall\fR of
265 the packages in the directory tree below its parent.  Unlike the
266 \fIPackages\fR file, nearly all of the lines in a \fIRelease\fR
267 file are relevant for setting APT priorities:
268 .TP
269 \fBthe Archive: line\fR
270 names the archive to which all the packages
271 in the directory tree belong.  For example, the line
272 "Archive: stable"
273 specifies that all of the packages in the directory
274 tree below the parent of the \fIRelease\fR file are in a
275 stable archive.  Specifying this value in the APT preferences file
276 would require the line:
277
278 .nf
279 Pin: release a=stable
280 .fi
281 .TP
282 \fBthe Version: line\fR
283 names the release version.  For example, the
284 packages in the tree might belong to Debian GNU/Linux release
285 version 3.0.  Note that there is normally no version number for the
286 testing and unstable distributions because they
287 have not been released yet.  Specifying this in the APT preferences
288 file would require one of the following lines.
289
290 .nf
291 Pin: release v=3.0
292 Pin: release a=stable, v=3.0
293 Pin: release 3.0
294 .fi
295 .TP
296 \fBthe Component: line\fR
297 names the licensing component associated with the
298 packages in the directory tree of the \fIRelease\fR file.
299 For example, the line "Component: main" specifies that
300 all the packages in the directory tree are from the main
301 component, which entails that they are licensed under terms listed
302 in the Debian Free Software Guidelines.  Specifying this component
303 in the APT preferences file would require the line:
304
305 .nf
306 Pin: release c=main
307 .fi
308 .TP
309 \fBthe Origin: line\fR
310 names the originator of the packages in the
311 directory tree of the \fIRelease\fR file.  Most commonly, this is
312 Debian\&.  Specifying this origin in the APT preferences file
313 would require the line:
314
315 .nf
316 Pin: release o=Debian
317 .fi
318 .TP
319 \fBthe Label: line\fR
320 names the label of the packages in the directory tree
321 of the \fIRelease\fR file.  Most commonly, this is
322 Debian\&.  Specifying this label in the APT preferences file
323 would require the line:
324
325 .nf
326 Pin: release l=Debian
327 .fi
328 .PP
329 All of the \fIPackages\fR and \fIRelease\fR
330 files retrieved from locations listed in the \fB\fIsources.list\fB\fR(5) file are stored
331 in the directory \fI/var/lib/apt/lists\fR, or in the file named
332 by the variable Dir::State::Lists in the \fIapt.conf\fR file.
333 For example, the file
334 \fIdebian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release\fR
335 contains the \fIRelease\fR file retrieved from the site
336 debian.lcs.mit.edu for binary-i386 architecture
337 files from the contrib component of the unstable
338 distribution.
339 .SS "OPTIONAL LINES IN AN APT PREFERENCES RECORD"
340 .PP
341 Each record in the APT preferences file can optionally begin with
342 one or more lines beginning with the word Explanation:\&.
343 This provides a place for comments.
344 .PP
345 The Pin-Priority: line in each APT preferences record is
346 optional.  If omitted, APT assigs a priority of 1 less than the last value
347 specified on a line beginning with Pin-Priority: release ...\&.
348 .SH "EXAMPLES"
349 .SS "TRACKING STABLE"
350 .PP
351 The following APT preferences file will cause APT to assign a
352 priority higher than the default (500) to all package versions belonging
353 to a stable distribution and a prohibitively low priority to
354 package versions belonging to other Debian distributions.
355
356 .nf
357 Explanation: Uninstall or do not install any Debian-originated
358 Explanation: package versions other than those in the stable distro
359 Package: *
360 Pin: release a=stable
361 Pin-Priority: 900
362
363 Package: *
364 Pin: release o=Debian
365 Pin-Priority: -10
366 .fi
367 .PP
368 With a suitable \fB\fIsources.list\fB\fR(5) file and the above preferences file,
369 any of the following commands will cause APT to upgrade to the
370 latest stable version(s).
371
372 .nf
373 apt-get install \fIpackage-name\fR
374 apt-get upgrade
375 apt-get dist-upgrade
376 .fi
377 .PP
378 The following command will cause APT to upgrade the specified
379 package to the latest version from the testing distribution;
380 the package will not be upgraded again unless this command is given
381 again.
382
383 .nf
384 apt-get install \fIpackage\fR/testing
385 .fi
386 .SS "TRACKING TESTING OR UNSTABLE"
387 .PP
388 The following APT preferences file will cause APT to assign
389 a high priority to package versions from the testing
390 distribution, a lower priority to package versions from the
391 unstable distribution, and a prohibitively low priority
392 to package versions from other Debian distributions.
393
394 .nf
395 Package: *
396 Pin: release a=testing
397 Pin-Priority: 900
398
399 Package: *
400 Pin: release a=unstable
401 Pin-Priority: 800
402
403 Package: *
404 Pin: release o=Debian
405 Pin-Priority: -10
406 .fi
407 .PP
408 With a suitable \fB\fIsources.list\fB\fR(5) file and the above preferences file,
409 any of the following commands will cause APT to upgrade to the latest
410 testing version(s).
411
412 .nf
413 apt-get install \fIpackage-name\fR
414 apt-get upgrade
415 apt-get dist-upgrade
416 .fi
417 .PP
418 The following command will cause APT to upgrade the specified
419 package to the latest version from the unstable distribution.
420 Thereafter, \fBapt-get upgrade\fR will upgrade
421 the package to the most recent testing version if that is
422 more recent than the installed version, otherwise, to the most recent
423 unstable version if that is more recent than the installed
424 version.
425
426 .nf
427 apt-get install \fIpackage\fR/unstable
428 .fi
429 .SH "SEE ALSO"
430 .PP
431 \fBapt-get\fR(8) \fBapt-cache\fR(8) \fB\fIapt.conf\fB\fR(5) \fB\fIsources.list\fB\fR(5)
432 .SH "BUGS"
433 .PP
434 See the APT bug page <URL:http://bugs.debian.org/src:apt>\&.  
435 If you wish to report a bug in APT, please see
436 \fI/usr/share/doc/debian/bug-reporting.txt\fR or the \fBreportbug\fR(1) command.
437 .SH "AUTHOR"
438 .PP
439 APT was written by the APT team <apt@packages.debian.org>\&.