7.6. Overwriting files and replacing packages - Replaces

Packages can declare in their control file that they should overwrite files in certain other packages, or completely replace other packages. The Replaces control field has these two distinct purposes.

7.6.1. Overwriting files in other packages

It is usually an error for a package to contain files which are on the system in another package. However, if the overwriting package declares that it Replaces the one containing the file being overwritten, then dpkg will replace the file from the old package with that from the new. The file will no longer be listed as “owned” by the old package and will be taken over by the new package. Normally, Breaks should be used in conjunction with Replaces. 4

For example, if a package foo is split into foo and foo-data starting at version 1.2-3, foo-data would have the fields

  1. Replaces: foo (<< 1.2-3)
  2. Breaks: foo (<< 1.2-3)

in its control file. The new version of the package foo would normally have the field

  1. Depends: foo-data (>= 1.2-3)

(or possibly Recommends or even Suggests if the files moved into foo-data are not required for normal operation).

If a package is completely replaced in this way, so that dpkg does not know of any files it still contains, it is considered to have “disappeared”. It will be marked as not wanted on the system (selected for removal) and “Not-Installed”. Any conffiles details noted for the package will be ignored, as they will have been taken over by the overwriting package. The package’s postrm script will be run with a special argument to allow the package to do any final cleanup required. See Summary of ways maintainer scripts are called. 5

For this usage of Replaces, virtual packages (see Virtual packages - Provides) are not considered when looking at a Replaces field. The packages declared as being replaced must be mentioned by their real names.

This usage of Replaces only takes effect when both packages are at least partially on the system at once. It is not relevant if the packages conflict unless the conflict has been overridden.

7.6.2. Replacing whole packages, forcing their removal

Second, Replaces allows the packaging system to resolve which package should be removed when there is a conflict (see Conflicting binary packages - Conflicts). This usage only takes effect when the two packages do conflict, so that the two usages of this field do not interfere with each other.

In this situation, the package declared as being replaced can be a virtual package, so for example, all mail transport agents (MTAs) would have the following fields in their control files:

  1. Provides: mail-transport-agent
  2. Conflicts: mail-transport-agent
  3. Replaces: mail-transport-agent

ensuring that only one MTA can be unpacked at any one time. See Virtual packages - Provides for more information about this example.