Debian dependency errors have a special talent for appearing when you are trying to install one tiny utility and somehow turning the afternoon into an archaeological dig through package metadata. Messages such as unmet dependencies, held broken packages, or package is not configured yet sound dramatic, but most are recoverable without reinstalling the operating system or offering your laptop to the nearest volcano.
The safest approach is to diagnose the package state first, let APT propose a solution, and use lower-level dpkg commands only when necessary. This guide explains that process step by step, including fixes for interrupted installations, held packages, incompatible repositories, version conflicts, local DEB files, and stubborn maintainer scripts.
What Causes Dependency Errors on Debian?
A Debian package rarely lives alone. It may require particular libraries, utilities, language runtimes, or minimum versions of other packages. These relationships are recorded in fields such as Depends, Pre-Depends, Breaks, Conflicts, and Replaces. APT reads that metadata and attempts to select a compatible set of packages before anything is installed.
A dependency error occurs when APT cannot create that compatible set or when an installation stops halfway through. For example, a package may be unpacked but not configured because its setup script failed, the machine lost power, the disk became full, or a required package was unavailable. Debian’s APT guide specifically describes failed installations and difficult package relationships as common routes into a broken package state.
Common triggers include:
- An interrupted installation or upgrade
- Outdated package indexes
- Packages placed on hold
- Repositories from different Debian releases
- Third-party repositories providing incompatible versions
- A local
.debpackage installed without its dependencies - Insufficient disk space or inodes
- A failing pre-installation or post-installation script
- Incorrect APT pinning rules
Start by Reading the Entire Error Message
Do not focus only on the final line. The useful information usually appears several lines above it. APT normally identifies the package causing the conflict, the version it requires, and the version selected for installation.
A typical error might look like this:
This tells you that example-app needs version 2.4 or newer of libexample2, while APT currently considers version 2.1 the preferred candidate. The real question is therefore not “Why is Debian broken?” but “Why is APT selecting version 2.1?” Possible answers include an old package index, a held package, an outdated repository, or an APT preference rule.
Before changing anything, simulate the proposed operation when possible:
The -s option performs a simulation. Review packages marked for installation, upgrade, downgrade, or removal. If APT proposes removing your desktop environment, database server, or half the operating system, decline the offer. A package manager is powerful, not psychic.
The Safe Repair Sequence for Most Debian Dependency Errors
The following sequence resolves a large percentage of broken dependency situations. Run one command at a time and read its output before moving to the next.
Step 1: Refresh the package indexes
This command downloads current repository metadata. It does not upgrade installed packages. If it reports unreachable repositories, missing release files, signature failures, or duplicate entries, correct those repository problems before attempting the installation again.
Step 2: Audit the package database
The audit checks for partially installed packages and inconsistent package records. The official dpkg documentation notes that it can detect packages left partially installed or packages with missing or obsolete control data, then suggest appropriate recovery actions.
Step 3: Configure unpacked packages
This tells dpkg to configure every package that has been unpacked but not fully configured. It is especially useful after a power loss, terminated terminal session, failed upgrade, or interrupted installer. Debian’s reference documentation lists both dpkg --audit and dpkg --configure -a as standard package-recovery operations.
Step 4: Ask APT to repair broken dependencies
The shorter equivalent is:
The --fix-broken option asks APT to calculate a solution for the broken dependency state. Depending on the situation, it may install missing dependencies, upgrade related packages, finish configuration, or remove a package that cannot be satisfied. Always inspect the proposed changes before confirming.
Step 5: Verify the result
This command analyzes installed and unpacked packages for unresolved dependency problems. A clean result normally ends without listing unmet dependencies.
Step 6: Retry the original installation
Replace package-name with the actual package. Do not rerun the original command until the package database is consistent, or you may simply pile a new error on top of the old one like an especially unhelpful sandwich.
How to Fix Held Broken Packages
The phrase held broken packages does not always mean a package has deliberately been held. It is sometimes a general message indicating that APT cannot resolve the requested package versions. Still, checking actual holds is quick:
A held package is protected from automatic installation, upgrade, or removal. If a listed package is blocking the dependency solution and you no longer need the hold, remove it with:
Do not unhold packages blindly. Holds may have been created to preserve application compatibility, maintain a specific kernel, or prevent a problematic upgrade. The apt-mark manual defines hold, unhold, and showhold as the supported tools for managing this state.
Check Which Package Version APT Is Selecting
When an error compares two versions, inspect the installed version, candidate version, and repositories offering the package:
Example output may resemble:
Here, the newer version exists, but it has a lower priority. That may be intentional, especially when the newer package comes from another release. APT preferences control which package version becomes the installation candidate, while apt-cache policy helps reveal those priorities.
Inspect custom pinning rules in:
Pins can solve specialized repository-management problems, but incorrect priorities can force incompatible versions or prevent required upgrades. Avoid copying random pinning recipes without understanding the target release, package pattern, and priority involved.
Repair Mixed or Misconfigured Repositories
Repository mixing is one of the most common causes of complicated Debian dependency errors. Problems arise when a system pulls core libraries from stable, applications from testing, and several packages from an unrelated third-party archive. Each source may be perfectly respectable by itself; together, they can behave like four people trying to steer one shopping cart.
Review all active sources:
Modern Debian installations may use deb822-style .sources files, while older configurations commonly use one-line .list entries. Both are managed through /etc/apt/sources.list and /etc/apt/sources.list.d/.
Look for:
- Different Debian codenames used together unintentionally
- Entries for testing or unstable on a stable system
- Repositories left over from a previous Debian release
- Duplicate repository definitions
- Third-party repositories that do not support your Debian version
- Repositories for the wrong CPU architecture
Temporarily disable suspicious third-party entries by moving their files out of /etc/apt/sources.list.d/ or changing an enabled field to disabled where appropriate. Then run:
Debian’s documentation warns that mixing archives requires careful compatibility management and specifically notes that Debian and Ubuntu repositories are not intended to be combined.
Fix Dependency Errors After Installing a Local DEB File
The low-level command below installs the specified file but does not independently retrieve all missing dependencies:
If that leaves the package unconfigured, run:
APT will examine the package metadata and attempt to install required dependencies from your configured repositories. When installing future local packages, use APT where supported:
The leading ./ matters because it tells APT that the argument is a local file rather than a repository package name. Even then, the package can be installed only if compatible dependencies are available for your Debian release and architecture.
Check Disk Space, Inodes, and Package Downloads
A dependency problem may actually be the aftermath of an installation that stopped because the filesystem filled up. Check both storage space and inodes:
Pay particular attention to /, /var, /boot, and any separate filesystem holding APT’s cache. You can clear downloaded package archives with:
After freeing space, resume configuration and repair dependencies:
Do not assume that several gigabytes free on your home partition means the root filesystem is healthy. Separate partitions enjoy creating this exact sort of practical joke.
When Package Index Files Are Corrupted or Stale
If apt update reports malformed package lists, repeated hash mismatches, or parsing errors, rebuild the local package indexes:
This removes downloaded repository indexes, not installed software. APT downloads fresh copies during the next update. Before using the command, verify that the path is typed exactly as shown. The shell does not provide a complimentary undo button for creative uses of rm -rf.
After a successful update, run:
Reinstall a Damaged Package
If dependency resolution succeeds but files belonging to a package are missing or damaged, reinstall it:
If the package is not currently configurable, repair the general package state first:
You can also inspect which installed package owns a file:
Reinstallation is more appropriate for missing packaged files than deleting package-database records or manually copying libraries from another machine.
Diagnose a Failing Maintainer Script
Some packages remain broken because their preinst, postinst, prerm, or postrm script exits with an error. The command output usually identifies the script and package involved.
Review recent package activity:
Debian records APT terminal output and package-state changes in these logs, making them useful for identifying the command that started the failure and the package that never completed configuration.
Common script failures involve missing configuration directories, unavailable services, invalid configuration files, or commands supplied by another package. Correct the underlying error and retry:
Do not casually edit files under /var/lib/dpkg/info/. Those scripts and metadata are part of the package database. Editing them may be justified during advanced recovery, but it should be a documented, package-specific decision with a backupnot an opening move inspired by a forum comment from 2011.
Use Forced Removal Only as a Last Resort
A severely damaged package may be marked as requiring reinstallation while also refusing normal removal. First try the ordinary method:
If normal removal is impossible and you have confirmed that the package is not essential, a last-resort command is:
Forced removal bypasses protections and can worsen the system if used on core packages. Never use it casually for packages such as libc6, dpkg, apt, systemd, the active kernel, or essential boot components. Make a backup or snapshot first, particularly on production systems.
Dependency Errors During a Debian Release Upgrade
A release upgrade is different from repairing one application. Do not skip major stable releases or change repository codenames and improvise the remaining steps. Debian recommends following the release notes for the exact source and destination releases, reviewing proposed removals, and completing upgrades in the documented order.
Before a major upgrade:
- Back up important data and system configuration
- Disable unsupported third-party repositories
- Resolve all existing package errors
- Check for held packages
- Ensure adequate free disk space
- Read the release notes for known package transitions
- Simulate the full upgrade and inspect removals
If the simulation proposes surprising removals, stop and investigate. A full upgrade can legitimately remove obsolete packages, but “surprising” and “legitimate” are not synonyms.
A Compact Troubleshooting Checklist
- Read the first relevant error, not only the final line.
- Run
sudo apt updateand correct repository errors. - Run
sudo dpkg --audit. - Run
sudo dpkg --configure -a. - Run
sudo apt --fix-broken install. - Verify with
sudo apt-get check. - Inspect holds with
apt-mark showhold. - Inspect package candidates with
apt-cache policy package-name. - Review repository suites and third-party sources.
- Check disk space, inodes, and package logs.
- Simulate dangerous-looking operations before approving them.
- Use forced removal only after safer methods fail.
Practical Experiences From Real-World Debian Dependency Troubleshooting
Experience 1: The error was caused by yesterday’s interrupted upgrade
A common scenario begins with a routine upgrade that appears to freeze. The terminal is closed, the machine is rebooted, and the next installation produces a wall of dependency complaints. The important clue is often a package marked unpacked rather than installed. In this situation, repeatedly running apt install adds noise without addressing the unfinished configuration. The useful sequence is dpkg --audit, followed by dpkg --configure -a. Once the pending setup scripts finish, apt --fix-broken install can retrieve anything that was missing. What initially looks like a complicated dependency puzzle is frequently just an incomplete transaction waiting to resume.
Experience 2: A third-party repository quietly became the package candidate
Another recurring case involves software installed from an external repository months earlier. The repository offers a newer version of a shared library, so APT selects it as the candidate. Later, an official Debian package requires the Debian build of that library or a tightly matched companion package. The error names the library, but the real cause is repository priority. Running apt-cache policy exposes the installed version, candidate version, and origin. Temporarily disabling the external source, refreshing the indexes, and reviewing the repair plan usually reveals a sane path back to consistent Debian packages. The lesson is simple: repository changes have a long memory, even when administrators do not.
Experience 3: “Held packages” did not involve an actual hold
The phrase you have held broken packages often sends users directly to apt-mark unhold. Sometimes apt-mark showhold returns nothing. That is not a contradiction; the message can describe a dependency set APT cannot change rather than an explicit hold. The next productive step is to inspect version candidates and repository suites. In many cases, one package belongs to stable while its required dependency is available only from testing, backports, or an obsolete vendor repository. Checking the actual package state prevents unnecessary changes and avoids the classic troubleshooting mistake of fixing the wording instead of fixing the cause.
Experience 4: The package manager was blamed for a full filesystem
A surprisingly large number of broken installations begin with a full /boot or /var filesystem. A package downloads successfully, starts unpacking, and fails when it cannot write another file. The next APT command reports dependencies because packages are now partially configured. Checking df -h and df -i early can save considerable time. After removing obsolete data or clearing the APT archive cache, the correct move is to resume configurationnot reinstall everything. Package managers are excellent at tracking state, but they cannot squeeze a new kernel into zero remaining bytes, no matter how politely you use sudo.
Experience 5: The proposed fix was more dangerous than the original error
APT’s resolver may occasionally propose removing a large collection of packages to satisfy one request. Technically, that can be a valid solution. Operationally, it may be terrible. Experienced administrators pause whenever a dependency repair proposes removing desktop metapackages, networking tools, database components, kernels, or essential libraries. They simulate the action, inspect package origins, and identify the version mismatch before approving anything. This habit matters more than memorizing a hundred commands. The safest Debian recovery is not the command that runs fastest; it is the one whose consequences you understand before pressing Enter.
Conclusion
To correct dependency errors on Debian, begin with package-state recovery rather than aggressive removal. Refresh the indexes, audit dpkg, configure partially installed packages, and let apt --fix-broken install calculate a repair. If that fails, inspect held packages, candidate versions, repository configuration, available disk space, and package logs.
Most dependency failures are symptoms of an interrupted transaction or inconsistent software sourcesnot evidence that Debian itself has collapsed into a smoking crater. Work methodically, review every proposed removal, and reserve forced commands for genuine last-resort recovery.
SEO Metadata
