What to do when apt-get fails

When you install an application package in a Debian-based system, sometimes prerequisite application packages are unavailable. These missing packages are known as broken dependencies. Left unresolved, they can cripple your system’s ability to install new packages. They’re a disaster that isn’t supposed to happen in Debian, thanks to the Advanced Packaging Tool (APT) and the scripts contained in Debian packages. That makes broken dependencies all the more devastating when they happen. Some users have even been known to reinstall the whole operating system, despairing of otherwise having a functioning package management system. However, depending on how the broken dependencies arose, you have several options to try before you consider reinstalling.

Package management in Debian-based distributions centers on apt-get, a utility with a high-level set of functions for package management. Normally, for Debian users, apt-get interacts with four online repositories — experimental, unstable, testing, and stable — as listed in each user’s /etc/apt/sources.list file. (The repositories may differ for users of some Debian-derived distributions.) CDs and even local directories can also serve as package sources. Apt-get is supported by a cluster of related utilities, including apt-cache, apt-config, and apt-listchanges.

Apt-get calls on dpkg, the command that actually installs and removes packages. Like apt-get, dpkg is also supported by related utilities, including dpkg-reconfigure and dpkg-deb.

The two commands have several interfaces, including Aptitude, Synaptic, KPackage, Gnome-Apt, and dselect. Several of these interfaces, in particular Aptitude and dselect, include some of the tools you need for recovering from broken dependencies. However, as usually happens when an administrative problem arises on GNU/Linux, you have the widest set of options if you open a terminal while logged in as the root user and type the commands directly.

When broken dependencies occur

One case in which you have limited options for recovering the system is when you are installing unofficial .deb packages from a third party, instead of from a Debian-approved source. Although more free and open source software (FOSS) projects provide Debian packages than they did five years ago, too often they build them without dependencies calculated. That leaves users in the same dependency hell that RPM users had to endure in the bad old days before Yum and apt4rpm.

In this case, the only way out is to patiently track down the dependencies and install them one at a time. The trouble is, often the dependencies are unique to the project and the developers never bothered to make Debian packages for them. Admittedly, converting RPMs with alien or building do-it-yourself Debian packages are possibilities, but these options may require more effort than a casual user would find worthwhile.

More often, broken dependencies result from attempts to upgrade specific packages or the entire system. Unsurprisingly, they usually happen when using the experimental or unstable repositories, whose contents are still being tested. However, problems with packages also occur in testing, and even occasionally in stable. Mixing sources from different Debian-derived distributions can also cause problems. A package may need programs that are not available from the repositories in /etc/apt/sources.list, or a newer version of a program. Sometimes, a requested package or dependency conflicts with an already installed package, and the scripts included in the .deb do not yet have a suggested solution, such as holding back a package or removing the conflicting one.

Many users perform system upgrades when a new official version of Debian is released. In such large upgrades, a few problems are only to be expected. Usually, though, information about problems and workarounds can be found via an Internet search, if you can stand waiting for a week or two. If you’re too impatient to wait, then you have a number of solutions that you can try on your own.

Preparing to find a solution

When broken dependencies occur, your first priority should be gathering information. The main source, of course, is messages generated by apt-get, which specify exactly what packages are causing problems. You can also run apt-get check to check for broken dependencies. If you still have Web access, you can also check the Debian bug-tracking system to see if anyone else is having the same problem.

If you know that your upgrading habits are risky, it’s also advisable to plan ahead and install packages that can help you when broken dependencies hit. Use apt-cache or the list of packages on the Debian Web site to look at the utilities and related programs for both apt-get and dpkg. An especially useful one is apt-listchanges, which shows the differences between two versions of the same package. If you’re comfortable with building Debian packages, you might also consider installing equivs, a utility for building packages that contain only dependency information.

Another useful tool is script, which allows you to save a log file of your recovery efforts from a command shell. By keeping this record, you can avoid repeating failed solutions and ensure that any information you gather isn’t lost.

Escalating solutions

No matter how the broken dependencies arise, you have several ways to resolve the problems. In the order in which you should try them (and in ascending order of consequences, if something goes wrong), are:

1. Wait to see if a bug-fix resolves the problem. You may speed this process by reporting your own experiences on the Debian bug-tracking system. On the whole, though, this is a more passive solution than most users would care for. After all, apt-get is all about instant gratification, right?

2. Check the broken dependencies’ availability. Run apt-get update to get the latest list of packages from your sources, then retry the installation. If it still isn’t working, edit /etc/apt/source.list by adding another source, then run apt-get install again. If the package is just announced, some mirrors may take a few days to have it and all its dependencies.

3. Run apt-get -f install or apt-get -f remove without specifying a package, to force completion of package installations. If you are attempting a system upgrade, then use apt-get upgrade -f dist-upgrade. You might want to add the --no-download switch, so that you are working only with packages already on your system, rather than downloading other ones and possibly compounding your problems.

   If neither command works, try them again specifying the packages of the broken dependencies one at a time, specifying either the version number (apt-get -f install packagename=versionnumber) or the repository (apt-get -f install -t repositorypackagename). You can use the list of packages on the Debian Web site to help choose the version number of the packages.

   Alternatively, try dpkg --configure -a to attempt to reconfigure partly installed packages another way.

   In my experience, these commands rarely solve dependency problems. Still, since they do the least possible violence to your system, you should try them before employing stronger measures. Some users suggest trying these options several times before giving up on them.

4. Use dpkg -r package to remove the packages causing problems, or dpkg --purge package to remove all traces of the packages from the system, including any installation files. Both these approaches are frequently successful.
5. Use dpkg --force-auto-select package and dpkg --force-all package, in that order. As the names suggest, the first option forces the installation of packages you select, and the second option turns on all --force options.

6. After making backups, manually edit the package causing the trouble in /var/cache/apt. If you open the control file in the package’s control.tar.gz archive, you may be able to change the package dependencies, then regain a working system by installing the package then automatically removing it. If the package is already
   partially installed, you may find useful information for further steps in the scripts located in /var/lib/dpkg/info. Files labelled .confiles may lead you to configuration files in the /etc/ directory, while .list files show which files a package installs. The occasional .preinst script, which runs before the package is installed, may also contain useful information. If you are comfortable writing shell or Perl scripts, you might even experiment with your own ways of making the package installable. These solutions
   require patience, and work best with expertise, but, even if they fail, they will teach you some of the fundamentals of the Debian package system.

   When you are finished with any modifications, run dpkg --configure -a to install with the modified scripts or packages. If you receive an error message about missing configuration files, check whether there is a configuration file for the package in /etc with an extension of .dpkg-new and use the mv command to rename it.

7. Use equivs to create a package that contains only dependency information. This solution can be combined with editing scripts for a greater chance of success. The main drawback the approach is that it requires knowledge of how Debian packages are built, or at least a detailed set of instructions prepared ahead of time. In the middle of a crisis, beginning or intermediate users probably won’t be open to learning anything new.
8. Try dpkg --force-downgrade to attempt to resolve problems by reverting to earlier versions of a package. Note, though, that --force-downgrade works without checking dependencies, so it can leave you worse off than you were before. Use it only as a forlorn, last-ditch effort.

By this point, if you still don’t have a working package management system, you can safely conclude that your system is unrepairable. A few hours older and more frustrated, you can begin to think about reinstalling the operating system without accusing yourself of wimping out — either that, or about resigning yourself to the fact that you won’t be installing anything new on your system unless it’s from a tar file.

Avoiding broken dependencies

When you have a working system — by whatever means — consider taking steps to avoid broken dependencies in the future. Given Debian’s reputation for slow testing, few users are likely to be content practicing safe computing and confining their installations to packages from the stable repository. However, there are at least three steps that you can take to protect yourself while still installing and upgrading with some freedom.

To start with, before installing or upgrading a package, check its dependencies on the Debian Web site. As a rule, the more libraries in a package’s dependencies — especially common ones, like glibc — the greater the chances of broken dependencies. In other words, upgrading gnome-desktop-environment is a higher risk undertaking than installing PySol. If you have a strong need for a particular program, this information may do little except inform you of the risk. However, if your interest in a program is casual, it may cause you to think twice.

If you regularly use experimental or unstable, you can supplement the information from the Debian site by scanning the Debian User’s mailing list to see what problems people are having. This step is time-consuming if you are a compulsive upgrader, but can often alert you to problems and solutions.

Finally, before you actually install, use the -s or --dry-run options with apt-get to simulate your results before actually facing them. This step alone may be enough to save you from disasters. Unfortunately, it is exactly the sort of step that is easy to forget at the end of the day.

The power of apt-get and dpkg is rightly considered a major feature of Debian distributions. Yet it’s worth remembering that the same power that provides convenience can lead to catastrophe if you’re careless. A little planning can go a long way in avoiding problems, or at least telling you the odds. And if catastrophe strikes anyway, the same power that got you into the situation may lead you out of it, if you work systematically through the options.

Bruce Byfield is a course designer and instructor, and a computer journalist who writes regularly for NewsForge and the Linux Journal Web site.