apt refuses to work because a package is broken or half-installed
apt install or apt upgrade stops and tells you to fix broken packages firstShort 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.
Fix it fast
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 --audit2Match what you see, then jump to its fix
- 1
dpkg --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
apt 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
dpkg --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
- 1
What does the error look like?
apt install or apt upgrade stops and tells you to fix broken packages firstdpkg --audit lists packages that are half-installed or half-configureda 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 --audit2Fix
Let dpkg finish the configuration step for everything that is pending.
sudo dpkg --configure -a3Verify
The audit prints nothing and apt works again.
sudo dpkg --audit
sudo apt updateConfirmed by manpages.ubuntu.com
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 install2Fix
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 install3Verify
A normal install completes, and autoremove clears what was only needed for the broken state.
sudo apt update && sudo apt upgrade
sudo apt autoremoveConfirmed by manpages.ubuntu.com
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-package2Fix
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 install3Verify
The package is gone from the audit and apt installs normally.
sudo dpkg --audit
dpkg -l | grep my-packageConfirmed by debian.org
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 fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
Apache warns that a ${VAR} config variable is not defined
${VAR} left unchanged in the configuration, with a warning in the error log
Apache expands ${VAR} from Define or from the shell environment that exists when the server starts.
3 causes, each with a fix