Using dpkg-divert to Override Debian Files

The dpkg-divert utility is the standard Debian mechanism for safely overriding files provided by other packages without causing package manager conflicts or having custom changes overwritten during system upgrades. By instructing dpkg to write a file to an alternate location instead of its default path, system administrators and software packagers can substitute custom versions of binaries, scripts, or configuration files while maintaining clean package integrity.

In Debian-based systems, dpkg strictly manages file ownership. When a package is upgraded, any file it owns is replaced with the new version from the archive. If an administrator replaces a package-provided binary directly, subsequent updates will overwrite that modification. Similarly, if a second package attempts to overwrite a file owned by an existing package, dpkg halts installation due to a file conflict. dpkg-divert solves both problems by intercepting dpkg operations at the database level.

When a diversion is registered, dpkg modifies its internal catalog of file paths. Whenever an installation or update attempts to unpack the targeted file, dpkg automatically redirects the incoming file to a specified diversion path (for example, /usr/bin/original.distrib). This ensures the vendor-supplied file remains safely stored on disk and receives official updates without interfering with the custom replacement positioned at the primary path.

Diversions generally fall into two categories:

• Local diversions: Created by system administrators to apply site-specific customizations. By default, adding a diversion sets it as local, which overrides the target file regardless of which package provides it.
• Package diversions: Created by custom or third-party Debian packages using pre-installation scripts (preinst). These specify --package <package-name>, ensuring the diversion only applies when that specific package is installed.

To divert a file, the --add and --rename options are typically used together. The --rename flag tells dpkg to actively move the existing file on the filesystem to its new diverted location immediately, rather than waiting for a future package installation to trigger the shift:

dpkg-divert --divert /usr/bin/target.distrib --rename /usr/bin/target

Once diverted, administrators can place their custom script or binary at /usr/bin/target. When the package owning /usr/bin/target is updated, the new version will write to /usr/bin/target.distrib, leaving the custom file untouched.

Removing a diversion restores standard dpkg behavior. The custom file must be deleted first, followed by running dpkg-divert with the --remove and --rename flags to return the diverted file to its original location:

rm /usr/bin/target
dpkg-divert --rename --remove /usr/bin/target

By decoupling local modifications from package-managed updates, dpkg-divert serves as an essential tool for maintaining non-standard environments, testing software patches, and creating wrapper scripts while preserving system stability.