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      Do not upgrade packages; When used in conjunction with <literal/install/
 329      <literal/no-upgrade/ will prevent packages listed from being upgraded
 330      if they are already installed.
 331      Configuration Item: <literal/APT::Get::Upgrade/.
 332      </VarListEntry>
 333
 334      <VarListEntry><term><option/--force-yes/</>
 335      <ListItem><Para>
 336      Force yes; This is a dangerous option that will cause apt to continue
 337      without prompting if it is doing something potentially harmful. It
 338      should not be used except in very special situations. Using
 339      <literal/force-yes/ can potentially destroy your system!
 340      Configuration Item: <literal/APT::Get::force-yes/.
 341      </VarListEntry>
 342
 343      <VarListEntry><term><option/--print-uris/</>
 344      <ListItem><Para>
 345      Instead of fetching the files to install their URIs are printed. Each
 346      URI will have the path, the destination file name, the size and the expected
 347      md5 hash. Note that the file name to write to will not always match
 348      the file name on the remote site! This also works with the
 349      <literal/source/ and <literal/update/ commands. When used with the
 350      <literal/update/ command the MD5 and size are not included, and it is
 351      up to the user to decompress any compressed files.
 352      Configuration Item: <literal/APT::Get::Print-URIs/.
 353      </VarListEntry>
 354
 355      <VarListEntry><term><option/--purge/</>
 356      <ListItem><Para>
 357      Use purge instead of remove for anything that would be removed.
 358      An asterisk ("*") will be displayed next to packages which are
 359      scheduled to be purged.
 360      Configuration Item: <literal/APT::Get::Purge/.
 361      </VarListEntry>
 362
 363      <VarListEntry><term><option/--reinstall/</>
 364      <ListItem><Para>
 365      Re-Install packages that are already installed and at the newest version.
 366      Configuration Item: <literal/APT::Get::ReInstall/.
 367      </VarListEntry>
 368
 369      <VarListEntry><term><option/--list-cleanup/</>
 370      <ListItem><Para>
 371      This option defaults to on, use <literal/--no-list-cleanup/ to turn it
 372      off. When on <command/apt-get/ will automatically manage the contents of
 373      <filename>&statedir;/lists</> to ensure that obsolete files are erased.
 374      The only  reason to turn it off is if you frequently change your source
 375      list.
 376      Configuration Item: <literal/APT::Get::List-Cleanup/.
 377      </VarListEntry>
 378
 379      <VarListEntry><term><option/-t/</>
 380                    <term><option/--target-release/</>
 381                    <term><option/--default-release/</>
 382      <ListItem><Para>
 383      This option controls the default input to the policy engine, it creates
 384      a default pin at priority 990 using the specified release string. The
 385      preferences file may further override this setting. In short, this option
 386      lets you have simple control over which distribution packages will be
 387      retrieved from. Some common examples might be
 388      <option>-t '2.1*'</> or <option>-t unstable</>.
 389      Configuration Item: <literal/APT::Default-Release/;
 390      see also the &apt-preferences; manual page.
 391      </VarListEntry>
 392
 393      <VarListEntry><term><option/--trivial-only/</>
 394      <ListItem><Para>
 395      Only perform operations that are 'trivial'. Logically this can be considered
 396      related to <option/--assume-yes/, where <option/--assume-yes/ will answer
 397      yes to any prompt, <option/--trivial-only/ will answer no.
 398      Configuration Item: <literal/APT::Get::Trivial-Only/.
 399      </VarListEntry>
 400
 401      <VarListEntry><term><option/--no-remove/</>
 402      <ListItem><Para>
 403      If any packages are to be removed apt-get immediately aborts without
 404      prompting.
 405      Configuration Item: <literal/APT::Get::Remove/
 406      </VarListEntry>
 407
 408      <VarListEntry><term><option/--only-source/</>
 409      <ListItem><Para>
 410      Only has meaning for the <literal/source/ command.  Indicates that the
 411      given source names are not to be mapped through the binary
 412      table.  This means that if this option is specified, the
 413      <literal/source/ command will only accept source package names as
 414      arguments, rather than accepting binary package names and looking
 415      up the corresponding source package.
 416      Configuration Item: <literal/APT::Get::Only-Source/
 417      </VarListEntry>
 418
 419      <VarListEntry><term><option/--diff-only/</><term><option/--tar-only/</>
 420      <ListItem><Para>
 421      Download only the diff or tar file of a source archive.
 422      Configuration Item: <literal/APT::Get::Diff-Only/ and
 423      <literal/APT::Get::Tar-Only/
 424      </VarListEntry>
 425
 426      <VarListEntry><term><option/--arch-only/</>
 427      <ListItem><Para>
 428      Only process architecture-dependent build-dependencies.
 429      Configuration Item: <literal/APT::Get::Arch-Only/
 430      </VarListEntry>
 431
 432      &apt-commonoptions;
 433
 434    </VariableList>
 435  </RefSect1>
 436
 437  <RefSect1><Title>Files</>
 438    <variablelist>
 439      <VarListEntry><term><filename>/etc/apt/sources.list</></term>
 440      <ListItem><Para>
 441      Locations to fetch packages from.
 442      Configuration Item: <literal/Dir::Etc::SourceList/.
 443      </VarListEntry>
 444
 445      <VarListEntry><term><filename>/etc/apt/apt.conf</></term>
 446      <ListItem><Para>
 447      APT configuration file.
 448      Configuration Item: <literal/Dir::Etc::Main/.
 449      </VarListEntry>
 450
 451      <VarListEntry><term><filename>/etc/apt/apt.conf.d/</></term>
 452      <ListItem><Para>
 453      APT configuration file fragments
 454      Configuration Item: <literal/Dir::Etc::Parts/.
 455      </VarListEntry>
 456
 457      <VarListEntry><term><filename>/etc/apt/preferences</></term>
 458      <ListItem><Para>
 459      Version preferences file.
 460      This is where you would specify "pinning",
 461      i.e. a preference to get certain packages
 462      from a separate source
 463      or from a different version of a distribution.
 464      Configuration Item: <literal/Dir::Etc::Preferences/.
 465      </VarListEntry>
 466
 467      <VarListEntry><term><filename>&cachedir;/archives/</></term>
 468      <ListItem><Para>
 469      Storage area for retrieved package files.
 470      Configuration Item: <literal/Dir::Cache::Archives/.
 471      </VarListEntry>
 472
 473      <VarListEntry><term><filename>&cachedir;/archives/partial/</></term>
 474      <ListItem><Para>
 475      Storage area for package files in transit.
 476      Configuration Item: <literal/Dir::Cache::Archives/ (implicit partial).
 477      </VarListEntry>
 478
 479      <VarListEntry><term><filename>&statedir;/lists/</></term>
 480      <ListItem><Para>
 481      Storage area for state information for each package resource specified in
 482      &sources-list;
 483      Configuration Item: <literal/Dir::State::Lists/.
 484      </VarListEntry>
 485
 486      <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
 487      <ListItem><Para>
 488      Storage area for state information in transit.
 489      Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
 490      </VarListEntry>
 491    </variablelist>
 492  </RefSect1>
 493
 494  <RefSect1><Title>See Also</>
 495    <para>
 496    &apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;,
 497    &apt-conf;, &apt-config;,
 498    The APT User's guide in &docdir;, &apt-preferences;, the APT Howto.
 499  </RefSect1>
 500
 501  <RefSect1><Title>Diagnostics</>
 502    <para>
 503    <command/apt-get/ returns zero on normal operation, decimal 100 on error.
 504  </RefSect1>
 505
 506  &manbugs;
 507  &manauthor;
 508
 509 </refentry>