Stop the dpkg diversion trap when files overlap

Technical Briefing | 10/4/2026

We have all been there. You try to install a package, and apt explodes with an error about a file conflict. Usually it is a simple case of two packages trying to own the same path. But sometimes, especially when dealing with proprietary agents or custom tooling, you hit a circular dependency that prevents you from swapping binaries. It is the kind of silent configuration failure that makes you regret ever touching the system packaging files.

Why diversion exists and why it is a double-edged sword

Dpkg diversions tell the package manager that a file is actually located somewhere else. It is a way to override a file provided by a package without causing the installer to choke. People often misuse this to hotfix production boxes, but it is actually a formal way to manage file ownership. If you ignore the diversion registry, you end up with a system that thinks a file belongs to a package that is no longer even installed.

dpkg-divert --list | grep "/usr/bin/some-binary"

• Use –add to force a file aside before it is replaced
• Always check the status before manually force-overwriting files
• Clean up the diversion once the package conflict is resolved to keep the database sane

Most admins assume that removing a package clears these diversions, but dpkg is persistent. If you do not explicitly remove the diversion, the placeholder file stays in the registry forever. Next time you have a weird shell behavior where a utility behaves differently than the man page suggests, check this registry. It might be a ghost diversion from a sysadmin who left three years ago.