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