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