- only build documentation in maintainer-mode, include prebuilt manuals
[apt.git] / doc / apt-get.8
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-GET" "8" "29 May 2006" "" ""
7
8 .SH NAME
9 apt-get \- APT package handling utility -- command-line interface
10 .SH SYNOPSIS
11
12 \fBapt-get\fR [ \fB-hvs\fR ] [ \fB-o=\fIconfig string\fB\fR ] [ \fB-c=\fIfile\fB\fR ] { \fBupdate\fR | \fBupgrade\fR | \fBinstall  \fIpkg\fB\fI ...\fB\fR | \fBremove  \fIpkg\fB\fI ...\fB\fR | \fBsource  \fIpkg\fB\fI ...\fB\fR | \fBbuild-dep  \fIpkg\fB\fI ...\fB\fR | \fBcheck\fR | \fBclean\fR | \fBautoclean\fR }
13
14 .SH "DESCRIPTION"
15 .PP
16 \fBapt-get\fR is the command-line tool for handling packages, and may be 
17 considered the user's "back-end" to other tools using the APT
18 library.  Several "front-end" interfaces exist, such as synaptic and
19 aptitude.
20 .PP
21 Unless the \fB-h\fR, or \fB--help\fR option is given, one of the
22 commands below must be present.
23 .TP
24 \fBupdate\fR
25 update is used to resynchronize the package index files from
26 their sources. The indexes of available packages are fetched from the
27 location(s) specified in \fI/etc/apt/sources.list\fR\&.
28 An update should always be 
29 performed before an upgrade or dist-upgrade\&.
30 .TP
31 \fBupgrade\fR
32 upgrade is used to install the newest versions of all packages 
33 currently installed on the system from the sources enumerated in
34 \fI/etc/apt/sources.list\fR\&. Packages currently installed with 
35 new versions available are retrieved and upgraded; under no circumstances 
36 are currently installed packages removed, or packages not already installed 
37 retrieved and installed. New versions of currently installed packages that 
38 cannot be upgraded without changing the install status of another package 
39 will be left at their current version. An update must be 
40 performed first so that \fBapt-get\fR knows that new versions of packages are 
41 available.
42 .TP
43 \fBdist-upgrade\fR
44 dist-upgrade, in addition to performing the function of 
45 upgrade, also intelligently handles changing dependencies 
46 with new versions of packages; \fBapt-get\fR has a "smart" conflict 
47 resolution system, and it will attempt to upgrade the most important 
48 packages at the expense of less important ones if necessary. 
49 The \fI/etc/apt/sources.list\fR file contains a list of locations 
50 from which to retrieve desired package files.
51 See also \fBapt_preferences\fR(5) for a mechanism for
52 overriding the general settings for individual packages.
53 .TP
54 \fBinstall\fR
55 install is followed by one or more packages desired for 
56 installation. Each package is a package name, not a fully qualified 
57 filename (for instance, in a Fedora Core system, glibc would be the 
58 argument provided, not glibc-2.4.8.i686.rpm). 
59 All packages required 
60 by the package(s) specified for installation will also be retrieved and 
61 installed. The \fI/etc/apt/sources.list\fR file is used to locate 
62 the desired packages. If a hyphen is appended to the package name (with 
63 no intervening space), the identified package will be removed if it is 
64 installed. Similarly a plus sign can be used to designate a package to 
65 install. These latter features may be used to override decisions made by 
66 apt-get's conflict resolution system.
67
68 A specific version of a package can be selected for installation by 
69 following the package name with an equals and the version of the package 
70 to select. This will cause that version to be located and selected for
71 install. Alternatively a specific distribution can be selected by 
72 following the package name with a slash and the version of the 
73 distribution or the Archive name (stable, testing, unstable).
74
75 Both of the version selection mechanisms can downgrade packages and must
76 be used with care.
77
78 Finally, the \fBapt_preferences\fR(5) mechanism allows you to
79 create an alternative installation policy for
80 individual packages.
81
82 If no package matches the given expression and the expression contains one
83 of '.', '?' or '*' then it is assumed to be a POSIX regular expression,
84 and it is applied
85 to all package names in the database. Any matches are then installed (or
86 removed). Note that matching is done by substring so 'lo.*' matches 'how-lo'
87 and 'lowest'. If this is undesired, anchor the regular expression
88 with a '^' or '$' character, or create a more specific regular expression.
89 .TP
90 \fBremove\fR
91 remove is identical to install except that packages are 
92 removed instead of installed. If a plus sign is appended to the package 
93 name (with no intervening space), the identified package will be 
94 installed instead of removed.
95 .TP
96 \fBsource\fR
97 source causes \fBapt-get\fR to fetch source packages. APT 
98 will examine the available packages to decide which source package to 
99 fetch. It will then find and download into the current directory the 
100 newest available version of that source package. Source packages are 
101 tracked separately from binary packages via rpm-src type lines 
102 in the \fB\fIsources.list\fB\fR(5) file. This probably will mean that you will not 
103 get the same source as the package you have installed or as you could 
104 install. If the --compile options is specified then the package will be 
105 compiled to a binary using rpmbuild, if --download-only is 
106 specified then the source package will not be unpacked.
107
108 A specific source version can be retrieved by postfixing the source name
109 with an equals and then the version to fetch, similar to the mechanism
110 used for the package files. This enables exact matching of the source 
111 package name and version, implicitly enabling the 
112 APT::Get::Only-Source option.
113
114 Note that source packages are not tracked like binary packages, they 
115 exist only in the current directory and are similar to downloading source
116 tar balls.
117 .TP
118 \fBbuild-dep\fR
119 build-dep causes apt-get to install/remove packages in an 
120 attempt to satisfy the build dependencies for a source package.
121 .TP
122 \fBcheck\fR
123 check is a diagnostic tool; it updates the package cache and checks 
124 for broken dependencies.
125 .TP
126 \fBclean\fR
127 clean clears out the local repository of retrieved package 
128 files. It removes everything but the lock file from 
129 \fI/var/cache/apt/archives/\fR and 
130 \fI/var/cache/apt/archives/partial/\fR\&. 
131 .TP
132 \fBautoclean\fR
133 Like clean, autoclean clears out the local 
134 repository of retrieved package files. The difference is that it only 
135 removes package files that can no longer be downloaded, and are largely 
136 useless. This allows a cache to be maintained over a long period without 
137 it growing out of control. The configuration option 
138 APT::Clean-Installed will prevent installed packages from being
139 erased if it is set to off.
140 .SH "OPTIONS"
141 .PP
142 All command line options may be set using the configuration file, the
143 descriptions indicate the configuration option to set. For boolean
144 options you can override the config file by using something like 
145 \fB-f-\fR,\fB--no-f\fR, \fB-f=no\fR or several other variations.
146 .TP
147 \fB-d\fR
148 .TP
149 \fB--download-only\fR
150 Download only; package files are only retrieved, not unpacked or installed.
151 Configuration Item: APT::Get::Download-Only\&.
152 .TP
153 \fB-f\fR
154 .TP
155 \fB--fix-broken\fR
156 Fix; attempt to correct a system with broken dependencies in            
157 place. This option, when used with install/remove, can omit any packages
158 to permit APT to deduce a likely solution. Any Package that are specified
159 must completely correct the problem. The option is sometimes necessary when 
160 running APT for the first time; APT itself does not allow broken package 
161 dependencies to exist on a system. It is possible that a system's 
162 dependency structure can be so corrupt as to require manual intervention 
163 Use of this option together with \fB-m\fR may produce an
164 error in some situations. 
165 Configuration Item: APT::Get::Fix-Broken\&.
166 .TP
167 \fB-m\fR
168 .TP
169 \fB--ignore-missing\fR
170 .TP
171 \fB--fix-missing\fR
172 Ignore missing packages; If packages cannot be retrieved or fail the    
173 integrity check after retrieval (corrupted package files), hold back    
174 those packages and handle the result. Use of this option together with  
175 \fB-f\fR may produce an error in some situations. If a package is 
176 selected for installation (particularly if it is mentioned on the 
177 command line) and it could not be downloaded then it will be silently 
178 held back.
179 Configuration Item: APT::Get::Fix-Missing\&.
180 .TP
181 \fB--no-download\fR
182 Disables downloading of packages. This is best used with 
183 \fB--ignore-missing\fR to force APT to use only the .rpms it has 
184 already downloaded.
185 Configuration Item: APT::Get::Download\&.
186 .TP
187 \fB-q\fR
188 .TP
189 \fB--quiet\fR
190 Quiet; produces output suitable for logging, omitting progress indicators.
191 More q's will produce more quiet up to a maximum of 2. You can also use
192 \fB-q=#\fR to set the quiet level, overriding the configuration file. 
193 Note that quiet level 2 implies \fB-y\fR, you should never use -qq 
194 without a no-action modifier such as -d, --print-uris or -s as APT may 
195 decided to do something you did not expect.
196 Configuration Item: quiet\&.
197 .TP
198 \fB-s\fR
199 .TP
200 \fB--simulate\fR
201 .TP
202 \fB--just-print\fR
203 .TP
204 \fB--dry-run\fR
205 .TP
206 \fB--recon\fR
207 .TP
208 \fB--no-act\fR
209 No action; perform a simulation of events that would occur but do not
210 actually change the system. 
211 Configuration Item: APT::Get::Simulate\&.
212
213 Simulate prints out
214 a series of lines each one representing an rpm operation, Configure (Conf),
215 Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with
216 and empty set of square brackets meaning breaks that are of no consequence
217 (rare).
218 .TP
219 \fB-y\fR
220 .TP
221 \fB--yes\fR
222 .TP
223 \fB--assume-yes\fR
224 Automatic yes to prompts; assume "yes" as answer to all prompts and run
225 non-interactively. If an undesirable situation, such as changing a held
226 package or removing an essential package occurs then apt-get 
227 will abort. 
228 Configuration Item: APT::Get::Assume-Yes\&.
229 .TP
230 \fB-u\fR
231 .TP
232 \fB--show-upgraded\fR
233 Show upgraded packages; Print out a list of all packages that are to be
234 upgraded. 
235 Configuration Item: APT::Get::Show-Upgraded\&.
236 .TP
237 \fB-V\fR
238 .TP
239 \fB--verbose-versions\fR
240 Show full versions for upgraded and installed packages.
241 Configuration Item: APT::Get::Show-Versions\&.
242 .TP
243 \fB-b\fR
244 .TP
245 \fB--compile\fR
246 .TP
247 \fB--build\fR
248 Compile source packages after downloading them.
249 Configuration Item: APT::Get::Compile\&.
250 .TP
251 \fB--ignore-hold\fR
252 Ignore package Holds; This causes \fBapt-get\fR to ignore a hold 
253 placed on a package. This may be useful in conjunction with 
254 dist-upgrade to override a large number of undesired holds. 
255 Configuration Item: APT::Ignore-Hold\&.
256 .TP
257 \fB--no-upgrade\fR
258 Do not upgrade packages; When used in conjunction with install
259 no-upgrade will prevent packages listed from being upgraded
260 if they are already installed. 
261 Configuration Item: APT::Get::Upgrade\&.
262 .TP
263 \fB--force-yes\fR
264 Force yes; This is a dangerous option that will cause apt to continue 
265 without prompting if it is doing something potentially harmful. It 
266 should not be used except in very special situations. Using 
267 force-yes can potentially destroy your system! 
268 Configuration Item: APT::Get::force-yes\&.
269 .TP
270 \fB--print-uris\fR
271 Instead of fetching the files to install their URIs are printed. Each
272 URI will have the path, the destination file name, the size and the expected
273 md5 hash. Note that the file name to write to will not always match
274 the file name on the remote site! This also works with the 
275 source and update commands. When used with the
276 update command the MD5 and size are not included, and it is
277 up to the user to decompress any compressed files.
278 Configuration Item: APT::Get::Print-URIs\&.
279 .TP
280 \fB--purge\fR
281 Use purge instead of remove for anything that would be removed.
282 An asterisk ("*") will be displayed next to packages which are
283 scheduled to be purged.
284 Configuration Item: APT::Get::Purge\&.
285 .TP
286 \fB--reinstall\fR
287 Re-Install packages that are already installed and at the newest version.
288 Configuration Item: APT::Get::ReInstall\&.
289 .TP
290 \fB--list-cleanup\fR
291 This option defaults to on, use --no-list-cleanup to turn it 
292 off. When on \fBapt-get\fR will automatically manage the contents of 
293 \fI/var/lib/apt/lists\fR to ensure that obsolete files are erased. 
294 The only  reason to turn it off is if you frequently change your source 
295 list. 
296 Configuration Item: APT::Get::List-Cleanup\&.
297 .TP
298 \fB-t\fR
299 .TP
300 \fB--target-release\fR
301 .TP
302 \fB--default-release\fR
303 This option controls the default input to the policy engine, it creates
304 a default pin at priority 990 using the specified release string. The
305 preferences file may further override this setting. In short, this option
306 lets you have simple control over which distribution packages will be
307 retrieved from. Some common examples might be 
308 \fB-t '2.1*'\fR or \fB-t unstable\fR\&.
309 Configuration Item: APT::Default-Release;
310 see also the \fBapt_preferences\fR(5) manual page.
311 .TP
312 \fB--trivial-only\fR
313 Only perform operations that are 'trivial'. Logically this can be considered
314 related to \fB--assume-yes\fR, where \fB--assume-yes\fR will answer 
315 yes to any prompt, \fB--trivial-only\fR will answer no. 
316 Configuration Item: APT::Get::Trivial-Only\&.
317 .TP
318 \fB--no-remove\fR
319 If any packages are to be removed apt-get immediately aborts without
320 prompting. 
321 Configuration Item: APT::Get::Remove
322 .TP
323 \fB--only-source\fR
324 Only has meaning for the source command.  Indicates that the
325 given source names are not to be mapped through the binary
326 table.  This means that if this option is specified, the
327 source command will only accept source package names as
328 arguments, rather than accepting binary package names and looking
329 up the corresponding source package.
330 Configuration Item: APT::Get::Only-Source
331 .TP
332 \fB--diff-only\fR
333 .TP
334 \fB--tar-only\fR
335 Download only the diff or tar file of a source archive. 
336 Configuration Item: APT::Get::Diff-Only and 
337 APT::Get::Tar-Only
338 .TP
339 \fB--arch-only\fR
340 Only process architecture-dependent build-dependencies.
341 Configuration Item: APT::Get::Arch-Only 
342 .TP
343 \fB-h\fR
344 .TP
345 \fB--help\fR
346 Show a short usage summary.
347 .TP
348 \fB-v\fR
349 .TP
350 \fB--version\fR
351 Show the program version.
352 .TP
353 \fB-c\fR
354 .TP
355 \fB--config-file\fR
356 Configuration File; Specify a configuration file to use. 
357 The program will read the default configuration file and then this 
358 configuration file. See \fB\fIapt.conf\fB\fR(5) for syntax information.     
359 .TP
360 \fB-o\fR
361 .TP
362 \fB--option\fR
363 Set a Configuration Option; This will set an arbitrary configuration 
364 option. The syntax is \fB-o Foo::Bar=bar\fR\&.
365 .SH "FILES"
366 .TP
367 \fB\fI/etc/apt/sources.list\fB\fR
368 Locations to fetch packages from.
369 Configuration Item: Dir::Etc::SourceList\&.
370 .TP
371 \fB\fI/etc/apt/apt.conf\fB\fR
372 APT configuration file.
373 Configuration Item: Dir::Etc::Main\&.
374 .TP
375 \fB\fI/etc/apt/apt.conf.d/\fB\fR
376 APT configuration file fragments
377 Configuration Item: Dir::Etc::Parts\&.
378 .TP
379 \fB\fI/etc/apt/preferences\fB\fR
380 Version preferences file.
381 This is where you would specify "pinning",
382 i.e. a preference to get certain packages
383 from a separate source
384 or from a different version of a distribution.
385 Configuration Item: Dir::Etc::Preferences\&.
386 .TP
387 \fB\fI/var/cache/apt/archives/\fB\fR
388 Storage area for retrieved package files.
389 Configuration Item: Dir::Cache::Archives\&.
390 .TP
391 \fB\fI/var/cache/apt/archives/partial/\fB\fR
392 Storage area for package files in transit.
393 Configuration Item: Dir::Cache::Archives (implicit partial). 
394 .TP
395 \fB\fI/var/lib/apt/lists/\fB\fR
396 Storage area for state information for each package resource specified in
397 \fB\fIsources.list\fB\fR(5)
398 Configuration Item: Dir::State::Lists\&.
399 .TP
400 \fB\fI/var/lib/apt/lists/partial/\fB\fR
401 Storage area for state information in transit.
402 Configuration Item: Dir::State::Lists (implicit partial).
403 .SH "SEE ALSO"
404 .PP
405 \fBapt-cache\fR(8), \fBapt-cdrom\fR(8), \fB\fIsources.list\fB\fR(5),
406 \fB\fIapt.conf\fB\fR(5), \fBapt-config\fR(8),
407 The APT User's guide in /usr/share/doc/apt/, \fBapt_preferences\fR(5), the APT Howto.
408 .SH "DIAGNOSTICS"
409 .PP
410 \fBapt-get\fR returns zero on normal operation, decimal 100 on error.
411 .SH "BUGS"
412 .PP
413 See the APT bug page <URL:http://bugs.debian.org/src:apt>\&.  
414 If you wish to report a bug in APT, please see
415 \fI/usr/share/doc/debian/bug-reporting.txt\fR or the \fBreportbug\fR(1) command.
416 .SH "AUTHOR"
417 .PP
418 APT was written by the APT team <apt@packages.debian.org>\&.