APT User's Guide



Version 3.1.3



Table of Contents

1. General
1.1. Anatomy of the Package System
2. apt-get
3. DSelect
4. The Interface
4.1. Startup
4.2. The Status Report
4.2.1. The Extra Package list
4.2.2. The Packages to Remove
4.2.3. The New Packages list
4.2.4. The Kept Back list
4.2.5. Held Packages warning
4.2.6. Final summary
4.3. The Status Display
4.4. Dpkg
   

The APT package currently contains two sections, the APT dselect method and the apt-get command line user interface. Both provide a way to install and remove packages as well as download new packages from the Internet.

   

The Debian packaging system has a large amount of information associated with each package to help assure that it integrates cleanly and easily into the system. The most prominent of its features is the dependency system.

   

The dependency system allows individual programs to make use of shared elements in the system such as libraries. It simplifies placing infrequently used portions of a program in separate packages to reduce the number of things the average user is required to install. Also, it allows for choices in mail transport agents, X servers and so on.

   

The first step to understanding the dependency system is to grasp the concept of a simple dependency. The meaning of a simple dependency is that a package requires another package to be installed at the same time to work properly.

   

For instance, mailcrypt is an emacs extension that aids in encrypting email with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a simple dependency on GPG. Also, because it is an emacs extension it has a simple dependency on emacs, without emacs it is completely useless.

   

The other important dependency to understand is a conflicting dependency. It means that a package, when installed with another package, will not work and may possibly be extremely harmful to the system. As an example consider a mail transport agent such as sendmail, exim or qmail. It is not possible to have two mail transport agents installed because both need to listen to the network to receive mail. Attempting to install two will seriously damage the system so all mail transport agents have a conflicting dependency with all other mail transport agents.

   

As an added complication there is the possibility for a package to pretend to be another package. Consider that exim and sendmail for many intents are identical, they both deliver mail and understand a common interface. Hence, the package system has a way for them to declare that they are both mail-transport-agents. So, exim and sendmail both declare that they provide a mail-transport-agent and other packages that need a mail transport agent depend on mail-transport-agent. This can add a great deal of confusion when trying to manually fix packages.

   

At any given time a single dependency may be met by packages that are already installed or it may not be. APT attempts to help resolve dependency issues by providing a number of automatic algorithms that help in selecting packages for installation.

   

apt-get provides a simple way to install packages from the command line. Unlike dpkg, apt-get does not understand .deb files, it works with the package's proper name and can only install .deb archives from a Source.

   

The first [1] thing that should be done before using apt-get is to fetch the package lists from the Sources so that it knows what packages are available. This is done with apt-get update. For instance,

   
# apt-get update
Get http://ftp.de.debian.org/debian/ stable/binary-i386/ Packages
Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
Reading Package Lists... Done
Building Dependency Tree... Done
   

Once updated there are several commands that can be used:

   
upgrade

Upgrade will attempt to gently upgrade the whole system. Upgrade will never install a new package or remove an existing package, nor will it ever upgrade a package that might cause some other package to break. This can be used daily to relatively safely upgrade the system. Upgrade will list all of the packages that it could not upgrade, this usually means that they depend on new packages or conflict with some other package. dselect or apt-get install can be used to force these packages to install.

install

Install is used to install packages by name. The package is automatically fetched and installed. This can be useful if you already know the name of the package to install and do not want to go into a GUI to select it. Any number of packages may be passed to install, they will all be fetched. Install automatically attempts to resolve dependency problems with the listed packages and will print a summary and ask for confirmation if anything other than its arguments are changed.

dist-upgrade

Dist-upgrade is a complete upgrader designed to simplify upgrading between releases of Debian. It uses a sophisticated algorithm to determine the best set of packages to install, upgrade and remove to get as much of the system to the newest release. In some situations it may be desired to use dist-upgrade rather than spend the time manually resolving dependencies in dselect. Once dist-upgrade has completed then dselect can be used to install any packages that may have been left out.

It is important to closely look at what dist-upgrade is going to do, its decisions may sometimes be quite surprising.

   

apt-get has several command line options that are detailed in its man page, apt-get(8). The most useful option is -d which does not install the fetched files. If the system has to download a large number of package it would be undesired to start installing them in case something goes wrong. When -d is used the downloaded archives can be installed by simply running the command that caused them to be downloaded again without -d.



   

[1] If you are using an http proxy server you must set the http_proxy environment variable first, see sources.list(5)

   

The APT dselect method provides the complete APT system with the dselect package selection GUI. dselect is used to select the packages to be installed or removed and APT actually installs them.

   

To enable the APT method you need to select [A]ccess in dselect and then choose the APT method. You will be prompted for a set of Sources which are places to fetch archives from. These can be remote Internet sites, local Debian mirrors or CD-ROMs. Each source can provide a fragment of the total Debian archive, APT will automatically combine them to form a complete set of packages. If you have a CD-ROM then it is a good idea to specify it first and then specify a mirror so that you have access to the latest bug fixes. APT will automatically use packages on your CD-ROM before downloading from the Internet.

   
   Set up a list of distribution source locations

 Please give the base URL of the debian distribution.
 The access schemes I know about are: http file

 For example:
      file:/mnt/debian,
      https://deb.debian.org/debian,
      http://deb.debian.org/debian,


 URL [http://llug.sep.bnl.gov/debian]:
   

The Sources setup starts by asking for the base of the Debian archive, defaulting to an HTTP mirror. Next it asks for the distribution to get.

   
 Please give the distribution tag to get or a path to the
 package file ending in a /. The distribution
 tags are typically something like: stable unstable testing

 Distribution [stable]:
   

The distribution refers to the Debian version in the archive, stable refers to the latest released version and unstable refers to the developmental version.

   
 Please give the components to get
 The components are typically something like: main contrib non-free non-free-firmware

 Components [main contrib non-free non-free-firmware]:
   

The components list refers to the list of sub distributions to fetch. The distribution is split up based on software licenses, main being DFSG free packages while contrib and non-free contain things that have various restrictions placed on their use and distribution.

   

Any number of sources can be added, the setup script will continue to prompt until you have specified all that you want.

   

Before starting to use dselect it is necessary to update the available list by selecting [U]pdate from the menu. This is a superset of apt-get update that makes the fetched information available to dselect. [U]pdate must be performed even if apt-get update has been run before.

   

You can then go on and make your selections using [S]elect and then perform the installation using [I]nstall. When using the APT method the [C]onfig and [R]emove commands have no meaning, the [I]nstall command performs both of them together.

   

By default APT will automatically remove the package (.deb) files once they have been successfully installed. To change this behavior place Dselect::clean "prompt"; in /etc/apt/apt.conf.

   

Both that APT dselect method and apt-get share the same interface. It is a simple system that generally tells you what it will do and then goes and does it. [2] After printing out a summary of what will happen APT then will print out some informative status messages so that you can estimate how far along it is and how much is left to do.

   

Before all operations except update, APT performs a number of actions to prepare its internal state. It also does some checks of the system's state. At any time these operations can be performed by running apt-get check.

   
# apt-get check
Reading Package Lists... Done
Building Dependency Tree... Done
   

The first thing it does is read all the package files into memory. APT uses a caching scheme so this operation will be faster the second time it is run. If some of the package files are not found then they will be ignored and a warning will be printed when apt-get exits.

   

The final operation performs a detailed analysis of the system's dependencies. It checks every dependency of every installed or unpacked package and considers if it is OK. Should this find a problem then a report will be printed out and apt-get will refuse to run.

   
# apt-get check
Reading Package Lists... Done
Building Dependency Tree... Done
You might want to run 'apt --fix-broken install' to correct these.
Sorry, but the following packages have unmet dependencies:
  9fonts: Depends: xlib6g but it is not installed
  uucp: Depends: mailx but it is not installed
  blast: Depends: xlib6g (>= 3.3-5) but it is not installed
  adduser: Depends: perl-base but it is not installed
  aumix: Depends: libgpmg1 but it is not installed
  debiandoc-sgml: Depends: sgml-base but it is not installed
  bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
  cthugha: Depends: svgalibg1 but it is not installed
           Depends: xlib6g (>= 3.3-5) but it is not installed
  libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
   

In this example the system has many problems, including a serious problem with libreadlineg2. For each package that has unmet dependencies a line is printed out indicating the package with the problem and the dependencies that are unmet. A short explanation of why the package has a dependency problem is also included.

   

There are two ways a system can get into a broken state like this. The first is caused by dpkg missing some subtle relationships between packages when performing upgrades. [3]. The second is if a package installation fails during an operation. In this situation a package may have been unpacked without its dependents being installed.

   

The second situation is much less serious than the first because APT places certain constraints on the order that packages are installed. In both cases supplying the -f option to apt-get will cause APT to deduce a possible solution to the problem and then continue on. The APT dselect method always supplies the -f option to allow for easy continuation of failed maintainer scripts.

   

However, if the -f option is used to correct a seriously broken system caused by the first case then it is possible that it will either fail immediately or the installation sequence will fail. In either case it is necessary to manually use dpkg (possibly with forcing options) to correct the situation enough to allow APT to proceed.

   

Before proceeding apt-get will present a report on what will happen. Generally the report reflects the type of operation being performed but there are several common elements. In all cases the lists reflect the final state of things, taking into account the -f option and any other relevant activities to the command being executed.

   

During the download of archives and package files APT prints out a series of status messages.

   
# apt-get update
Get:1 http://ftp.de.debian.org/debian/ stable/main Packages
Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
Get:4 http://ftp.de.debian.org/debian/ unstable/binary-i386/ Packages
Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
   

The lines starting with Get are printed out when APT begins to fetch a file while the last line indicates the progress of the download. The first percent value on the progress line indicates the total percent done of all files. Unfortunately since the size of the Package files is unknown apt-get update estimates the percent done which causes some inaccuracies.

   

The next section of the status line is repeated once for each download thread and indicates the operation being performed and some useful information about what is happening. Sometimes this section will simply read Forking which means the OS is loading the download module. The first word after the [ is the fetch number as shown on the history lines. The next word is the short form name of the object being downloaded. For archives it will contain the name of the package that is being fetched.

   

Inside of the single quote is an informative string indicating the progress of the negotiation phase of the download. Typically it progresses from Connecting to Waiting for file to Downloading or Resuming. The final value is the number of bytes downloaded from the remote site. Once the download begins this is represented as 102/10.2k indicating that 102 bytes have been fetched and 10.2 kilobytes is expected. The total size is always shown in 4 figure notation to preserve space. After the size display is a percent meter for the file itself. The second last element is the instantaneous average speed. This values is updated every 5 seconds and reflects the rate of data transfer for that period. Finally is shown the estimated transfer time. This is updated regularly and reflects the time to complete everything at the shown transfer rate.

   

The status display updates every half second to provide a constant feedback on the download progress while the Get lines scroll back whenever a new file is started. Since the status display is constantly updated it is unsuitable for logging to a file, use the -q option to remove the status display.