]> git.saurik.com Git - apt.git/blame - doc/apt-get.8.sgml
0.5.7
[apt.git] / doc / apt-get.8.sgml
CommitLineData
b2e465d6
AL
1<!-- -*- mode: sgml; mode: fold -*- -->
2<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
3
4<!ENTITY % aptent SYSTEM "apt.ent">
5%aptent;
6
7]>
8
9<refentry>
10 &apt-docinfo;
11
12 <refmeta>
13 <refentrytitle>apt-get</>
14 <manvolnum>8</>
15 </refmeta>
16
17 <!-- Man page title -->
18 <refnamediv>
19 <refname>apt-get</>
20 <refpurpose>APT package handling utility -- command-line interface</>
21 </refnamediv>
22
23 <!-- Arguments -->
24 <refsynopsisdiv>
25 <cmdsynopsis>
09774285 26 <command>apt-get</>
b2e465d6
AL
27 <arg><option>-hvs</></arg>
28 <arg><option>-o=<replaceable/config string/</></arg>
29 <arg><option>-c=<replaceable/file/</></arg>
30 <group choice=req>
31 <arg>update</>
32 <arg>upgrade</>
33 <arg>dselect-upgrade</>
34 <arg>install <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
35 <arg>remove <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
36 <arg>source <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
37 <arg>build-dep <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
38 <arg>check</>
39 <arg>clean</>
40 <arg>autoclean</>
41 </group>
42 </cmdsynopsis>
43 </refsynopsisdiv>
44
45 <RefSect1><Title>Description</>
46 <para>
47 <command/apt-get/ is the command-line tool for handling packages, and may be
48 considered the user's "back-end" to other tools using the APT library.
49 <para>
de7f0f23 50 Unless the <option/-h/, or <option/--help/ option is given, one of the
09774285 51 commands below must be present.
b2e465d6
AL
52
53 <VariableList>
54 <VarListEntry><Term>update</Term>
55 <ListItem><Para>
56 <literal/update/ is used to resynchronize the package index files from
57 their sources. The indexes of available packages are fetched from the
58 location(s) specified in <filename>/etc/apt/sources.list</>.
59 For example, when using a Debian archive, this command retrieves and
60 scans the <filename>Packages.gz</> files, so that information about new
61 and updated packages is available. An <literal/update/ should always be
62 performed before an <literal/upgrade/ or <literal/dist-upgrade/. Please
63 be aware that the overall progress meter will be incorrect as the size
64 of the package files cannot be known in advance.
65 </VarListEntry>
66
67 <VarListEntry><Term>upgrade</Term>
68 <ListItem><Para>
69 <literal/upgrade/ is used to install the newest versions of all packages
70 currently installed on the system from the sources enumerated in
71 <filename>/etc/apt/sources.list</>. Packages currently installed with
72 new versions available are retrieved and upgraded; under no circumstances
73 are currently installed packages removed, or packages not already installed
74 retrieved and installed. New versions of currently installed packages that
75 cannot be upgraded without changing the install status of another package
76 will be left at their current version. An <literal/update/ must be
77 performed first so that <command/apt-get/ knows that new versions of packages are
78 available.
79 </VarListEntry>
80
81 <VarListEntry><Term>dselect-upgrade</Term>
82 <ListItem><Para>
de7f0f23
AL
83 <literal/dselect-upgrade/
84 is used in conjunction with the traditional Debian packaging
b2e465d6
AL
85 front-end, &dselect;. <literal/dselect-upgrade/
86 follows the changes made by &dselect; to the <literal/Status/
87 field of available packages, and performs the actions necessary to realize
88 that state (for instance, the removal of old and the installation of new
89 packages).
90 </VarListEntry>
91
92 <VarListEntry><Term>dist-upgrade</Term>
93 <ListItem><Para>
94 <literal/dist-upgrade/, in addition to performing the function of
95 <literal/upgrade/, also intelligently handles changing dependencies
96 with new versions of packages; <command/apt-get/ has a "smart" conflict
97 resolution system, and it will attempt to upgrade the most important
de7f0f23 98 packages at the expense of less important ones if necessary.
b2e465d6
AL
99 The <filename>/etc/apt/sources.list</> file contains a list of locations
100 from which to retrieve desired package files.
de7f0f23
AL
101 See also &apt-preferences; for a mechanism for
102 overriding the general settings for individual packages.
b2e465d6
AL
103 </VarListEntry>
104
105 <VarListEntry><Term>install</Term>
106 <ListItem><Para>
107 <literal/install/ is followed by one or more packages desired for
108 installation. Each package is a package name, not a fully qualified
109 filename (for instance, in a Debian GNU/Linux system, libc6 would be the
de7f0f23 110 argument provided, not <literal/libc6_1.9.6-2.deb/). All packages required
b2e465d6
AL
111 by the package(s) specified for installation will also be retrieved and
112 installed. The <filename>/etc/apt/sources.list</> file is used to locate
113 the desired packages. If a hyphen is appended to the package name (with
114 no intervening space), the identified package will be removed if it is
115 installed. Similarly a plus sign can be used to designate a package to
e35e72b1 116 install. These latter features may be used to override decisions made by
de7f0f23 117 apt-get's conflict resolution system.
b2e465d6
AL
118 <para>
119 A specific version of a package can be selected for installation by
120 following the package name with an equals and the version of the package
121 to select. This will cause that version to be located and selected for
122 install. Alternatively a specific distribution can be selected by
123 following the package name with a slash and the version of the
8835c5d0 124 distribution or the Archive name (stable, testing, unstable).
b2e465d6 125 <para>
e35e72b1 126 Both of the version selection mechanisms can downgrade packages and must
b2e465d6
AL
127 be used with care.
128 <para>
de7f0f23
AL
129 Finally, the &apt-preferences; mechanism allows you to
130 create an alternative installation policy for
131 individual packages.
132 <para>
b2e465d6 133 If no package matches the given expression and the expression contains one
de7f0f23
AL
134 of '.', '?' or '*' then it is assumed to be a POSIX regular expression,
135 and it is applied
b2e465d6
AL
136 to all package names in the database. Any matches are then installed (or
137 removed). Note that matching is done by substring so 'lo.*' matches 'how-lo'
de7f0f23
AL
138 and 'lowest'. If this is undesired, anchor the regular expression
139 with a '^' or '$' character, or create a more specific regular expression.
b2e465d6
AL
140 </VarListEntry>
141
142 <VarListEntry><Term>remove</Term>
143 <ListItem><Para>
e35e72b1 144 <literal/remove/ is identical to <literal/install/ except that packages are
b2e465d6
AL
145 removed instead of installed. If a plus sign is appended to the package
146 name (with no intervening space), the identified package will be
de7f0f23 147 installed instead of removed.
b2e465d6
AL
148 </VarListEntry>
149
150 <VarListEntry><Term>source</Term>
151 <ListItem><Para>
152 <literal/source/ causes <command/apt-get/ to fetch source packages. APT
153 will examine the available packages to decide which source package to
154 fetch. It will then find and download into the current directory the
155 newest available version of that source package. Source packages are
156 tracked separately from binary packages via <literal/deb-src/ type lines
157 in the &sources-list; file. This probably will mean that you will not
158 get the same source as the package you have installed or as you could
159 install. If the --compile options is specified then the package will be
160 compiled to a binary .deb using dpkg-buildpackage, if --download-only is
161 specified then the source package will not be unpacked.
162 <para>
163 A specific source version can be retrieved by postfixing the source name
164 with an equals and then the version to fetch, similar to the mechanism
165 used for the package files. This enables exact matching of the source
166 package name and version, implicitly enabling the
167 <literal/APT::Get::Only-Source/ option.
168
169 <para>
170 Note that source packages are not tracked like binary packages, they
171 exist only in the current directory and are similar to downloading source
172 tar balls.
173 </VarListEntry>
174
175 <VarListEntry><Term>build-dep</Term>
176 <ListItem><Para>
177 <literal/build-dep/ causes apt-get to install/remove packages in an
de7f0f23 178 attempt to satisfy the build dependencies for a source package.
b2e465d6
AL
179 </VarListEntry>
180
181 <VarListEntry><Term>check</Term>
182 <ListItem><Para>
183 <literal/check/ is a diagnostic tool; it updates the package cache and checks
184 for broken dependencies.
185 </VarListEntry>
186
187 <VarListEntry><Term>clean</Term>
188 <ListItem><Para>
189 <literal/clean/ clears out the local repository of retrieved package
190 files. It removes everything but the lock file from
191 <filename>&cachedir;/archives/</> and
c6649788 192 <filename>&cachedir;/archives/partial/</>. When APT is used as a
b2e465d6
AL
193 &dselect; method, <literal/clean/ is run automatically.
194 Those who do not use dselect will likely want to run <literal/apt-get clean/
195 from time to time to free up disk space.
196 </VarListEntry>
197
198 <VarListEntry><Term>autoclean</Term>
199 <ListItem><Para>
200 Like <literal/clean/, <literal/autoclean/ clears out the local
201 repository of retrieved package files. The difference is that it only
202 removes package files that can no longer be downloaded, and are largely
203 useless. This allows a cache to be maintained over a long period without
204 it growing out of control. The configuration option
205 <literal/APT::Clean-Installed/ will prevent installed packages from being
de7f0f23 206 erased if it is set to off.
b2e465d6
AL
207 </VarListEntry>
208 </VariableList>
209 </RefSect1>
210
211 <RefSect1><Title>Options</>
212 &apt-cmdblurb;
213
214 <VariableList>
215 <VarListEntry><term><option/-d/</><term><option/--download-only/</>
216 <ListItem><Para>
217 Download only; package files are only retrieved, not unpacked or installed.
218 Configuration Item: <literal/APT::Get::Download-Only/.
219 </VarListEntry>
220
221 <VarListEntry><term><option/-f/</><term><option/--fix-broken/</>
222 <ListItem><Para>
223 Fix; attempt to correct a system with broken dependencies in
224 place. This option, when used with install/remove, can omit any packages
225 to permit APT to deduce a likely soltion. Any Package that are specified
226 must completly correct the problem. The option is sometimes necessary when
227 running APT for the first time; APT itself does not allow broken package
228 dependencies to exist on a system. It is possible that a system's
229 dependency structure can be so corrupt as to require manual intervention
230 (which usually means using &dselect; or <command/dpkg --remove/ to eliminate some of
231 the offending packages). Use of this option together with <option/-m/ may produce an
232 error in some situations.
233 Configuration Item: <literal/APT::Get::Fix-Broken/.
234 </VarListEntry>
235
236 <VarListEntry><term><option/-m/</><term><option/--ignore-missing/</>
237 <term><option/--fix-missing/</>
238 <ListItem><Para>
239 Ignore missing packages; If packages cannot be retrieved or fail the
240 integrity check after retrieval (corrupted package files), hold back
241 those packages and handle the result. Use of this option together with
242 <option/-f/ may produce an error in some situations. If a package is
243 selected for installation (particularly if it is mentioned on the
244 command line) and it could not be downloaded then it will be silently
245 held back.
246 Configuration Item: <literal/APT::Get::Fix-Missing/.
247 </VarListEntry>
248
249 <VarListEntry><term><option/--no-download/</>
250 <ListItem><Para>
251 Disables downloading of packages. This is best used with
252 <option/--ignore-missing/ to force APT to use only the .debs it has
253 already downloaded.
254 Configuration Item: <literal/APT::Get::Download/.
255 </VarListEntry>
256
257 <VarListEntry><term><option/-q/</><term><option/--quiet/</>
258 <ListItem><Para>
259 Quiet; produces output suitable for logging, omitting progress indicators.
260 More q's will produce more quiet up to a maximum of 2. You can also use
261 <option/-q=#/ to set the quiet level, overriding the configuration file.
262 Note that quiet level 2 implies <option/-y/, you should never use -qq
263 without a no-action modifier such as -d, --print-uris or -s as APT may
264 decided to do something you did not expect.
265 Configuration Item: <literal/quiet/.
266 </VarListEntry>
267
268 <VarListEntry><term><option/-s/</>
269 <term><option/--simulate/</>
270 <term><option/--just-print/</>
271 <term><option/--dry-run/</>
272 <term><option/--recon/</>
273 <term><option/--no-act/</>
274 <ListItem><Para>
275 No action; perform a simulation of events that would occur but do not
276 actually change the system.
277 Configuration Item: <literal/APT::Get::Simulate/.
278 <para>
279 Simulate prints out
280 a series of lines each one representing a dpkg operation, Configure (Conf),
281 Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with
282 and empty set of square brackets meaning breaks that are of no consequence
283 (rare).
284 </VarListEntry>
285
286 <VarListEntry><term><option/-y/</><term><option/--yes/</>
287 <term><option/--assume-yes/</>
288 <ListItem><Para>
289 Automatic yes to prompts; assume "yes" as answer to all prompts and run
290 non-interactively. If an undesirable situation, such as changing a held
291 package or removing an essential package occurs then <literal/apt-get/
292 will abort.
293 Configuration Item: <literal/APT::Get::Assume-Yes/.
294 </VarListEntry>
295
296 <VarListEntry><term><option/-u/</><term><option/--show-upgraded/</>
297 <ListItem><Para>
298 Show upgraded packages; Print out a list of all packages that are to be
299 upgraded.
300 Configuration Item: <literal/APT::Get::Show-Upgraded/.
301 </VarListEntry>
302
ac625538
AL
303 <VarListEntry><term><option/-V/</><term><option/--verbose-versions/</>
304 <ListItem><Para>
305 Show full versions for upgraded and installed packages.
306 Configuration Item: <literal/APT::Get::Show-Versions/.
307 </VarListEntry>
308
b2e465d6
AL
309 <VarListEntry><term><option/-b/</><term><option/--compile/</>
310 <term><option/--build/</>
311 <ListItem><Para>
312 Compile source packages after downloading them.
313 Configuration Item: <literal/APT::Get::Compile/.
314 </VarListEntry>
315
316 <VarListEntry><term><option/--ignore-hold/</>
317 <ListItem><Para>
318 Ignore package Holds; This causes <command/apt-get/ to ignore a hold
319 placed on a package. This may be useful in conjunction with
320 <literal/dist-upgrade/ to override a large number of undesired holds.
321 Configuration Item: <literal/APT::Ignore-Hold/.
322 </VarListEntry>
323
324 <VarListEntry><term><option/--no-upgrade/</>
325 <ListItem><Para>
326 Do not upgrade packages; When used in conjunction with <literal/install/
327 <literal/no-upgrade/ will prevent packages listed from being upgraded
328 if they are already installed.
329 Configuration Item: <literal/APT::Get::Upgrade/.
330 </VarListEntry>
331
332 <VarListEntry><term><option/--force-yes/</>
333 <ListItem><Para>
334 Force yes; This is a dangerous option that will cause apt to continue
335 without prompting if it is doing something potentially harmful. It
336 should not be used except in very special situations. Using
337 <literal/force-yes/ can potentially destroy your system!
338 Configuration Item: <literal/APT::Get::force-yes/.
339 </VarListEntry>
340
341 <VarListEntry><term><option/--print-uris/</>
342 <ListItem><Para>
343 Instead of fetching the files to install their URIs are printed. Each
344 URI will have the path, the destination file name, the size and the expected
345 md5 hash. Note that the file name to write to will not always match
f0863b21 346 the file name on the remote site! This also works with the
c9aa0f15 347 <literal/source/ and <literal/update/ commands. When used with the
f0863b21
AL
348 <literal/update/ command the MD5 and size are not included, and it is
349 up to the user to decompress any compressed files.
350 Configuration Item: <literal/APT::Get::Print-URIs/.
b2e465d6
AL
351 </VarListEntry>
352
353 <VarListEntry><term><option/--purge/</>
354 <ListItem><Para>
355 Use purge instead of remove for anything that would be removed.
1a65cab4
AL
356 An asterisk ("*") will be displayed next to packages which are
357 scheduled to be purged.
b2e465d6
AL
358 Configuration Item: <literal/APT::Get::Purge/.
359 </VarListEntry>
360
361 <VarListEntry><term><option/--reinstall/</>
362 <ListItem><Para>
363 Re-Install packages that are already installed and at the newest version.
364 Configuration Item: <literal/APT::Get::ReInstall/.
365 </VarListEntry>
366
367 <VarListEntry><term><option/--list-cleanup/</>
368 <ListItem><Para>
369 This option defaults to on, use <literal/--no-list-cleanup/ to turn it
370 off. When on <command/apt-get/ will automatically manage the contents of
371 <filename>&statedir;/lists</> to ensure that obsolete files are erased.
372 The only reason to turn it off is if you frequently change your source
373 list.
374 Configuration Item: <literal/APT::Get::List-Cleanup/.
375 </VarListEntry>
376
377 <VarListEntry><term><option/-t/</>
378 <term><option/--target-release/</>
379 <term><option/--default-release/</>
380 <ListItem><Para>
381 This option controls the default input to the policy engine, it creates
382 a default pin at priority 990 using the specified release string. The
383 preferences file may further override this setting. In short, this option
384 lets you have simple control over which distribution packages will be
e35e72b1 385 retrieved from. Some common examples might be
b2e465d6 386 <option>-t '2.1*'</> or <option>-t unstable</>.
de7f0f23
AL
387 Configuration Item: <literal/APT::Default-Release/;
388 see also the &apt-preferences; manual page.
b2e465d6
AL
389 </VarListEntry>
390
391 <VarListEntry><term><option/--trivial-only/</>
392 <ListItem><Para>
e35e72b1 393 Only perform operations that are 'trivial'. Logically this can be considered
b2e465d6
AL
394 related to <option/--assume-yes/, where <option/--assume-yes/ will answer
395 yes to any prompt, <option/--trivial-only/ will answer no.
396 Configuration Item: <literal/APT::Get::Trivial-Only/.
397 </VarListEntry>
398
399 <VarListEntry><term><option/--no-remove/</>
400 <ListItem><Para>
401 If any packages are to be removed apt-get immediately aborts without
402 prompting.
403 Configuration Item: <literal/APT::Get::Remove/
404 </VarListEntry>
405
406 <VarListEntry><term><option/--only-source/</>
407 <ListItem><Para>
408 Only has meaning for the <literal/source/ command. indicates that the
409 given source names are not to be mapped through the binary table.
410 Configuration Item: <literal/APT::Get::Only-Source/
411 </VarListEntry>
412
413 <VarListEntry><term><option/--diff-only/</><term><option/--tar-only/</>
414 <ListItem><Para>
415 Download only the diff or tar file of a source archive.
416 Configuration Item: <literal/APT::Get::Diff-Only/ and
417 <literal/APT::Get::Tar-Only/
418 </VarListEntry>
09774285 419
45430cbf
AL
420 <VarListEntry><term><option/--arch-only/</>
421 <ListItem><Para>
422 Only process architecture-dependent build-dependencies.
423 Configuration Item: <literal/APT::Get::Arch-Only/
424 </VarListEntry>
425
09774285
AL
426 &apt-commonoptions;
427
b2e465d6
AL
428 </VariableList>
429 </RefSect1>
430
431 <RefSect1><Title>Files</>
432 <variablelist>
433 <VarListEntry><term><filename>/etc/apt/sources.list</></term>
434 <ListItem><Para>
de7f0f23 435 Locations to fetch packages from.
b2e465d6
AL
436 Configuration Item: <literal/Dir::Etc::SourceList/.
437 </VarListEntry>
438
ae7a4bf3
AL
439 <VarListEntry><term><filename>/etc/apt/apt.conf</></term>
440 <ListItem><Para>
441 APT configuration file.
442 Configuration Item: <literal/Dir::Etc::Main/.
443 </VarListEntry>
444
445 <VarListEntry><term><filename>/etc/apt/apt.conf.d/</></term>
446 <ListItem><Para>
447 APT configuration file fragments
448 Configuration Item: <literal/Dir::Etc::Parts/.
449 </VarListEntry>
450
451 <VarListEntry><term><filename>/etc/apt/preferences</></term>
452 <ListItem><Para>
de7f0f23
AL
453 Version preferences file.
454 This is where you would specify "pinning",
455 i.e. a preference to get certain packages
456 from a separate source
457 or from a different version of a distribution.
ae7a4bf3
AL
458 Configuration Item: <literal/Dir::Etc::Preferences/.
459 </VarListEntry>
460
b2e465d6
AL
461 <VarListEntry><term><filename>&cachedir;/archives/</></term>
462 <ListItem><Para>
de7f0f23 463 Storage area for retrieved package files.
b2e465d6
AL
464 Configuration Item: <literal/Dir::Cache::Archives/.
465 </VarListEntry>
466
467 <VarListEntry><term><filename>&cachedir;/archives/partial/</></term>
468 <ListItem><Para>
de7f0f23 469 Storage area for package files in transit.
b2e465d6
AL
470 Configuration Item: <literal/Dir::Cache::Archives/ (implicit partial).
471 </VarListEntry>
472
473 <VarListEntry><term><filename>&statedir;/lists/</></term>
474 <ListItem><Para>
de7f0f23 475 Storage area for state information for each package resource specified in
b2e465d6
AL
476 &sources-list;
477 Configuration Item: <literal/Dir::State::Lists/.
478 </VarListEntry>
479
480 <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
481 <ListItem><Para>
de7f0f23 482 Storage area for state information in transit.
b2e465d6
AL
483 Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
484 </VarListEntry>
485 </variablelist>
486 </RefSect1>
487
488 <RefSect1><Title>See Also</>
489 <para>
041c7082 490 &apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;, &apt-conf;,
de7f0f23 491 The APT User's guide in &docdir;, &apt-preferences;, the APT Howto.
b2e465d6
AL
492 </RefSect1>
493
494 <RefSect1><Title>Diagnostics</>
495 <para>
496 <command/apt-get/ returns zero on normal operation, decimal 100 on error.
497 </RefSect1>
498
499 &manbugs;
500 &manauthor;
501
502</refentry>