📛 NAME
dpkg-divert — override a package's version of a file
🚀 Quick Reference
| Use Case | Command | Description |
|---|
| 📋 List all diversions | dpkg-divert --list | Show all file diversions on the system |
| ➕ Add diversion | dpkg-divert --divert /path/to/diverted --rename /path/to/file | Divert a file to a new location, renaming it |
| ➖ Remove diversion | dpkg-divert --rename --remove /path/to/file | Remove a diversion and restore original file |
| 📦 Divert for specific package | dpkg-divert --package pkgname --divert /path/to/diverted --rename /path/to/file | Divert file for all packages except specified one |
| 🔍 Find diverting package | dpkg-divert --listpackage /path/to/file | Show which package diverts a file |
| 🏷️ Get real filename | dpkg-divert --truename /path/to/file | Print the real name for a diverted file |
📖 Synopsis
dpkg-divert [option...] command
📝 Description
dpkg-divert is the utility used to set up and update the list of diversions.
File diversions are a way of forcing dpkg(1) not to install a file into its location, but to a diverted location. Diversions can be used through the Debian package scripts to move a file away when it causes a conflict. System administrators can also use it to override some package's configuration file, or whenever some files (which aren't marked as "conffiles") need to be preserved by dpkg, when installing a newer version of a package which contains those files.
⚙️ Commands
- [--add] file — Add a diversion for file. The file is currently not renamed, see --rename.
- --remove file — Remove a diversion for file. The file is currently not renamed, see --rename.
- --list glob-pattern — List diversions matching glob-pattern.
- --listpackage file — Print the name of the package that diverts file (since dpkg 1.15.0). Prints LOCAL if file is locally diverted and nothing if file is not diverted.
- --truename file — Print the real name for a diverted file.
🔧 Options
- --admindir directory — Set the administrative directory to directory. Defaults to «/var/lib/dpkg».
- --instdir directory — Set the installation directory (since dpkg 1.19.2). Defaults to «/».
- --root directory — Set the root directory to directory, which sets the installation directory to «directory» and the administrative directory to «directory/var/lib/dpkg» (since dpkg 1.19.2).
- --divert divert-to — divert-to is the location where the versions of file, as provided by other packages, will be diverted.
- --local — Specifies that all packages' versions of this file are diverted. No exceptions — whatever package is installed, the file is diverted. Useful for admins installing a locally modified version.
- --package package — package is the name of a package whose copy of file will not be diverted. File will be diverted for all packages except package.
- --quiet — Quiet mode, no verbose output.
- --rename — Actually move the file aside (or back). Aborts if destination file exists. Common behavior for non-Essential package diversions.
- --no-rename — Specifies the file should not be renamed while adding/removing the diversion in the database (since dpkg 1.19.1). Intended for Essential package diversions where temporary disappearance is unacceptable. This is the default, but will change in dpkg 1.20.x.
- --test — Test mode; don't perform any changes, just demonstrate.
- -?, --help — Show usage message and exit.
- --version — Show version and exit.
🚪 Exit Codes
- 0 ✅ — The requested action was successfully performed.
- 2 ❌ — Fatal or unrecoverable error due to invalid command-line usage, or interactions with the system (database access, memory allocations, etc.).
🌍 Environment
- DPKG_ROOT — If set and --instdir or --root not specified, used as filesystem root directory (since dpkg 1.19.2).
- DPKG_ADMINDIR — If set and --admindir or --root not specified, used as the dpkg data directory.
- DPKG_MAINTSCRIPT_PACKAGE — If set and --local and --package not specified, dpkg-divert will use it as the package name.
- DPKG_COLORS — Sets the color mode (since dpkg 1.18.5). Accepted values: auto (default), always, never.
📁 Files
- /var/lib/dpkg/diversions — Contains the current list of diversions. Located in the dpkg administration directory alongside other important files like status or available. Note: dpkg-divert preserves the old copy with -old extension before replacing it.
📌 Notes
- When adding, default is --local and --divert original.distrib. When removing, --package or --local and --divert must match if specified.
- Directories can't be diverted with dpkg-divert.
- ⚠️ Care should be taken when diverting shared libraries — ldconfig(8) creates a symbolic link based on DT_SONAME. Since ldconfig doesn't honor diverts (only dpkg does), the symlink may point at the diverted library if it has the same SONAME as the undiverted one.
💡 Examples
To divert all copies of /usr/bin/example to /usr/bin/example.foo, directing all packages providing it to install as /usr/bin/example.foo, performing the rename if required:
dpkg-divert --divert /usr/bin/example.foo --rename /usr/bin/example
To remove that diversion:
dpkg-divert --rename --remove /usr/bin/example
To divert any package trying to install /usr/bin/example to /usr/bin/example.foo, except your own wibble package:
dpkg-divert --package wibble --divert /usr/bin/example.foo \
--rename /usr/bin/example
To remove that diversion:
dpkg-divert --package wibble --rename --remove /usr/bin/example
🔗 See Also
dpkg(1)
