Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

apt refuses to work because a package is broken or half-installed

Errorapt install or apt upgrade stops and tells you to fix broken packages first

Short answer

Ask dpkg which packages are in a bad state, then fix them in order of risk. Run dpkg --configure -a for an interrupted install, apt --fix-broken install for missing dependencies, and only when a package script keeps failing, remove it with --force-remove-reinstreq. Skip forced removal until the first two have failed.

  • Applies to Ubuntu 24.04, Debian 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Let dpkg list what it considers unfinished. An empty answer means the problem is dependencies, not a stuck package.

    sudo dpkg --audit
  2. 2Match what you see, then jump to its fix

    1. 1dpkg --audit names packages that are unpacked but not configured, or started but not completedAn earlier install or upgrade was cut off before it finishedFix
    2. 2apt reports unmet dependencies or held broken packages while dpkg --audit is emptyA package needs a dependency that is missing or at the wrong versionFix
    3. 3dpkg --configure -a or apt remove fails again on the same package, and the error points at its prerm, postrm or postinst scriptA package's own removal script keeps failingFix

What does the error look like?

  • apt install or apt upgrade stops and tells you to fix broken packages first
  • dpkg --audit lists packages that are half-installed or half-configured
  • a package cannot be removed because its prerm or postrm script fails

Cause 1 of 3

An earlier install or upgrade was cut off before it finished

1Check

dpkg tracks a state for every package. Unpacked-but-unconfigured and half-configured are what a killed install, a closed SSH session or a power loss leaves behind.

sudo dpkg --audit

2Fix

Let dpkg finish the configuration step for everything that is pending.

sudo dpkg --configure -a

3Verify

The audit prints nothing and apt works again.

sudo dpkg --audit
sudo apt update

Confirmed by manpages.ubuntu.com

Did this fix it?

Cause 2 of 3

A package needs a dependency that is missing or at the wrong version

1Check

A package was installed with dpkg -i from a downloaded file, or a repository dropped a version, so a dependency is absent. Run the command without -y: apt prints what it would change and waits, so answer n if the list looks wrong.

sudo apt --fix-broken install

2Fix

Let apt work out what is needed and install or remove packages to make the set consistent. Read the list it prints before you confirm.

sudo apt --fix-broken install

3Verify

A normal install completes, and autoremove clears what was only needed for the broken state.

sudo apt update && sudo apt upgrade
sudo apt autoremove

Confirmed by manpages.ubuntu.com

Did this fix it?

Cause 3 of 3

A package's own removal script keeps failing

1Check

dpkg runs the maintainer scripts stored under /var/lib/dpkg/info. If one of them exits with an error, the package stays half-installed and blocks apt.

ls /var/lib/dpkg/info/ | grep my-package

2Fix

Find out why the script fails and fix that first. If the package is marked as needing reinstallation and cannot be removed any other way, dpkg can force the removal. This can leave some of its files behind that dpkg then forgets, so do it for one package at a time.

sudo dpkg --remove --force-remove-reinstreq my-package
sudo apt --fix-broken install

3Verify

The package is gone from the audit and apt installs normally.

sudo dpkg --audit
dpkg -l | grep my-package

Confirmed by debian.org

Did this fix it?

How do I stop it coming back?

  • Run long upgrades inside tmux or screen so a dropped SSH session cannot interrupt dpkg.
  • Do not install downloaded .deb files with dpkg -i when apt install ./file.deb can resolve dependencies for you.
  • Keep enough free disk space on / and /var before an upgrade.
  • Avoid dpkg --force-* options except to repair a specific package, and say why in your notes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.