An apt-get primer


Author: Bruce Byfield

If any single program defines the Debian Linux project, that program is apt-get. apt-get is Debian’s main tool for installing and removing software. Working with the .deb package format, apt-get offers sophisticated package management that few Red Hat Package Manager RPM-based distributions can match.

Besides the convenience, an advantage of apt-get is that it reduces the chances of falling into dependency hell, that limbo where software installation fails for lack of another piece of software, whose installation fails for lack of another piece of software, and so on. If you know how Debian’s archive system works, and how to choose the sources that apt-get uses, and use a few precautions in your upgrades, then the chances are that dependency problems will never bedevil you. Should you descend into dependency hell anyway, apt-get offers useful tools for climbing out of it.

Knowing the Debian archives

Most of the time, apt-get works with the Debian online archives, downloading packages from the Internet and installing them. More than 200 official mirror sites exist, as well as dozens of unofficial ones. Depending on which Debian-based distribution you are using, repositories are either entered automatically or selected by you during installation.

You can get a complete list of official archives from the Debian Mirror Site page. Many unofficial archives are available at, including backports to earlier versions of Debian; experimental, the archive for new and untested packages; and archives for Debian-compatible versions of Java. You use these unofficial archives, needless to say, at your own risk.

Each archive is for one of the three basic Debian distributions, each named after a character in the movie “Toy Story.” Stable (codename woody) is the oldest, most tested and reliable version of Debian. Notoriously, it is usually long out of date, but, if you’re setting up a server or want absolute safety, it’s the one to choose. At the opposite extreme, unstable (codename sid) contains all the latest versions of software that have been minimally tested by Debian developers. Although usually reliable, unstable can cause dependency problems on any given day. For that reason, many users prefer to use testing (sarge), seeing it as a balance between the dependability of stable and the timeliness of unstable. Many run mixed systems consisting of testing with a dash of unstable packages.

Each archive is further divided into areas listed as directories in the sources list. The main area contains software that meets the Debian Free Software Guidelines — in other words, software that Debian defines as free. The contrib area contains software that is free itself, but depends on non-free software. The non-free area, as its name implies, contains software that doesn’t meet DFSG standards. Although some Debian developers would prefer to get rid of contrib and non-free altogether, so far the two areas continue to be part of Debian.

Occasionally, you also see non-US, which denotes software — often cryptography tools — that cannot be exported from the U.S. for defense reasons. Just as often, though, non-US packages are stored in a separate archive.

Working with sources

The archives that apt-get uses on a system are listed in a file called /etc/apt/sources.list. Each entry follows a standard format:

deb [server-type] [address] [directories] [areas]

For example:

deb main contrib non-free

If the entry contains deb-src rather than deb, then the archive contains source files, not packaged software.

Most archives are HTTP or FTP servers. However, you can also list a file source to point to a directory to which you downloaded or assembled a Debian package. For example:

deb file://root download

More rarely, you might encounter an rsh or SSH server.

Typically, each source has a line commented out above it — that is, one starting with a # character. This commented line identifies the source, and perhaps gives some details about its use.

A root user can add other archives to sources.list by using a text editor. To avoid typos, you should paste the archives into source.list. If you want to use the fastest archive available, use apt-get to install netselect-apt, a script that determines the fastest archive for your machine, and creates a sources list based on its finding. Similarly, you can use apt-get cdrom to add a CD that is currently in a drive to sources.list.

If the distribution doesn’t include it automatically, you should also add the line:

deb stable updates main

This archive contains all the security updates to the Debian stable distribution. You can substitute woody for stable to get updates for the testing distribution instead; unstable, though, has no equivalent. Either way, you should either update your system with it regularly, or else subscribe to the debian-security-announce mailing list to know when new security updates are available.

If you only occasionally use unstable or an unofficial archive, most of the time you’ll want to keep them commented out when not using them. In other words, put a # character at the start of the line. That way, apt-get won’t use the archive, and you’ll be spared dependency problems caused by carelessness.

More importantly, commenting out an archive is a way to control how apt-get selects packages. During installation, apt-get uses the archive with the latest version of the program being installed. Since apt-get also installs any other software that the requested program needs, having a testing or unstable archive enabled can sometimes cause version problems. You can avoid this problem by commenting out unstable sources (and testing sources, if you’re really cautious) except when you’re using them.

After adding or removing a comment from a line that lists an archive, save sources.list, then run the command apt-get update while logged in as root. Otherwise, apt-get will use the last version of sources.list, and your caution will be wasted.

Researching packages

Before running apt-get, consult the Debian Packages page, which lets you search for available packages and find their version numbers and their dependencies.

Occasionally, the dependencies list a conflict with another package. Even more importantly, if you’re raiding the unstable distribution to get the latest packages for your stable or testing installation, you can determine the level of risk. The more libraries included among the dependencies, and the more widespread their use, the greater the chance that your efforts will break your system. You can also compare the required versions with the ones installed on your system, either by using the Web page or by running dpkg -l. dpkg is the utility that actually handles the packages; apt-get is simply a tool for handling dpkg more efficiently.

Large programs, such as the GNOME environment, often have a dummy package. A dummy package does not contain programs itself, but installs all the packages needed by the program at once, so that you don’t have to install them individually. In theory, of course, installing a separate package such as gnome-panel should install the rest of GNOME as dependencies. In practice, though, using a dummy package is usually a better guarantee that everything you need will be installed.

If a package is very new, your chosen mirror may not have it yet. When that happens, either try adding another archive to sources.list, or wait a day or two until the archive is updated.

Installing with apt-get

After you’ve edited and updated sources.list and researched the available packages, actually installing a package is an anti-climax. All you need to do is log in as root and type:

apt-get install [package-name]

For example, to install the GIMP, you would enter:

apt-get install gimp

Notice that no version number is needed. Instead, apt-get installs the latest version of the package in all the available sources. If none of the versions is newer than what is already installed, then nothing is installed.

If you choose, however, you can choose a particular version number. For example, to install version 2.2 of the GIMP, type:

apt-get install gimp=2.2

Instead, you may prefer to install by distribution. For instance, to get the version of the GIMP currently available in unstable, you would type:

apt-get install -t unstable gimp

For source packages, the commands are similar, except that you use source instead of install for the command. Also, if you want to compile the source packages after downloading them, add the -b switch. The source files are downloaded to the current directory.

Before apt-get runs, it summarizes the actions that it is about to perform (unless a program is very small and has no dependencies, or else has unique ones). It lists the new packages it will install, the packages to be upgraded, and the total hard drive space needed during installation and afterward. At the end of the summary, you must choose whether to continue or to stop. This is yet another of apt-get’s safeguards. Read the summary carefully, applying the same rules as when you researched: The more libraries, and the more basic the libraries, the more likely you are to run into problems. If you have the least doubt, stop the process. Before actually installing, try apt-get with the -s option to simulate the action and see what the results would be.

Assuming that you go forward, apt-get will download and install the packages, summarizing its actions each step of the way, and report the success or failure of the installation.

In some cases, debconf runs, requiring you to make system setup choices to work with the new program. As the name suggests, debconf is a Debian Configuration script. Debconf explains any system setup changes that need to be made to configure the program you’re installing, then gives you a list of possible choices. These choices can be confusing, but you can get into no real trouble by accepting the defaults. If you later decide that you have made a mistake, you can run debconf again, or remove and reinstall the package to correct your choices. To avoid making choices at all, you can use the --yes option to answer all questions automatically.

As an alternative to installing individual packages — even dummy packages — you can upgrade your entire system. However, this choice increases the level of risk. Apt-get’s upgrade command updates all packages on your system with the latest versions available. The only drawback is that, if a newer version of a package has new dependencies, they may not be installed. The dist-upgrade command avoids this problem, but can also cause dependency problems if you choose to upgrade to unstable on a bad day. In addition, the conventional wisdom is that, if you are using stable, you should upgrade to testing before upgrading to unstable. Neither upgrade option is likely to be trouble-free, but, barring problems, you can upgrade your system while continuing to work on it; apt-get swaps files in and out of memory, so you can work largely uninterrupted.

No matter how you install, you can reclaim disk space when you are finished by typing apt-get clean . This command removes everything from the /var/cache/apt and /var/cache/apt/archives/partial directories. As an alternative, you can use the autoclean command instead, which removes only the files for packages that can no longer be downloaded using the present list of sources.

You can also delete packages by using the remove command. Like the install command, remove uses only package names, but can specify version numbers or Debian distributions to work upon. In fact, the two commands are so similar that adding a plus sign when using remove actually changes the operation to an install.

When dependency problems descend

As you can see, apt-get minimizes most of the chances for dependency problems. All the same, ignorance, impulsiveness, or plain carelessness (either yours or the Debian package maintainer’s) can overcome the best safeguards. For any of these reasons, you can have dependency problems, even on a Debian-based system.

Dependency problems are not Armageddon for your system. Usually, you can continue to run already installed programs. You may even be able to continue installing other programs once you manually delete the lock file from /var/cache/apt/. But serious dependency problems can prevent you from installing using apt-get, forcing a re-install in your future. A dependency problem with KDE, for example, may prevent you from installing new packages entirely.

Fortunately, Debian offers several ways of dealing with broken dependencies. The usual place to start is with the check command, which locates broken packages. In some cases, repeating apt-get dist-upgrade several times can correct the problem. Similarly, the surgical use of dpkg --purge to remove a problem package can sometimes reduce your system to a state where you can start to rebuild.

If these options fail, you can try using some of apt-get’s otheroptions:

  • -f: Used with or without a command to try to fix dependencies.
  • -m: Ignores missing and corrupted packages during an installation. Can be used with install or remove to return a system to a state from which you can rebuild.
  • -ignore-hold: Ignores holds that are placed on a package that may be contributing to problems.
  • -s: Reports on the status of the package listed. Useful for tracking down the packages causing problems.

However, all these alternatives require patience and skill to use. Instead of relying on them, most users should use caution beforehand instead. Research and restraint can prevent hours of troubleshooting.

Apt-get interfaces

Over the years, apt-get has spawned several interfaces. Except for the commercial alternatives, all of these interfacts can themselves be installed using apt-get. So far, none matches apt-get itself. The venerable dselect provides a text-based interface, but is so inadequate for the thousands of packages that Debian offers today that new users stagger away from it whimpering softly. For a text-based interface, aptitude is a more practical choice, although navigating it is only marginally easier.

On the desktop, synaptic keeps close to the language of apt-get in its interface, and has a handy editor for sources.list. However, it hides complete dependency listings in a menu, and its interface needs tweaking. By contrast, kpackage, KDE’s multi-distribution package manager, is exactly the opposite: its commands are remote from the language of apt-get, yet arranged in a functional interface. For ease of use, Linspire’s Click-N-Run and Xandros’ Network are similar services, but both require you to rely on a single commercial vendor. Of all the desktop tools, gnome-apt makes the most functionality available, but its interface is currently undergoing a much-needed overhaul.

All these tools have a fan base, but none has a significant advantage over the apt-get utility itself. If anything, they tend to be less functional, and most are only minimally helpful when resolving dependency problems. This is one case in which command-line macho seems justified.


Many desktop Linux users today shun the command line altogether. Yet, with its power and convenience, apt-get is an example of the command line at its best. Available for years, it’s the main reason why, although Red Hat, SUSE, and Mandrake are the major players in commercial Linux, Debian-derivatives such as Xandros, Progeny, and Linspire regularly appear in the marketplace.

Connectiva has ported apt-get to the world of RPM packages, and, in the future, the Linux Core Consortium seems likely to build on this effort. For now, though, apt-get remains a key reason for using Debian.

Bruce Byfield is a computer journalist and free software instructor.


  • Linux