[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Ubuntu Policy Manual
Chapter 7 - Declaring relationships between packages

7.1 Syntax of relationship fields

These fields all have a uniform syntax. They are a list of package names separated by commas.

In the Depends, Recommends, Suggests, Pre-Depends, Build-Depends and Build-Depends-Indep control file fields of the package, which declare dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols |. In such a case, if any one of the alternative packages is installed, that part of the dependency is considered to be satisfied.

All of the fields except for Provides may restrict their applicability to particular versions of each named package. This is done in parentheses after each individual package name; the parentheses should contain a relation from the list below followed by a version number, in the format described in Version, Section 5.6.12.

The relations allowed are <<, <=, =, >= and >> for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively. The deprecated forms < and > were used to mean earlier/later or equal, rather than strictly earlier/later, so they should not appear in new packages (though dpkg still supports them).

Whitespace may appear at any point in the version specification subject to the rules in Syntax of control files, Section 5.1, and must appear where it's necessary to disambiguate; it is not otherwise significant. All of the relationship fields may span multiple lines. For consistency and in case of future changes to dpkg it is recommended that a single space be used after a version relationship and before a version number; it is also conventional to put a single space after each comma, on either side of each vertical bar, and before each open parenthesis. When wrapping a relationship field, it is conventional to do so after a comma and before the space following that comma.

For example, a list of dependencies might appear as:

     Package: mutt
     Version: 1.3.17-1
     Depends: libc6 (>= 2.2.1), exim | mail-transport-agent

All fields that specify build-time relationships (Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep) may be restricted to a certain set of architectures. This is indicated in brackets after each individual package name and the optional version specification. The brackets enclose a list of Debian architecture names separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with exclamation marks while others aren't.) If the current Debian host architecture is not in this list and there are no exclamation marks in the list, or it is in the list with a prepended exclamation mark, the package name and the associated version specification are ignored completely for the purposes of defining the relationships.

For example:

     Source: glibc
     Build-Depends-Indep: texinfo
     Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
       hurd-dev [hurd-i386], gnumach-dev [hurd-i386]

requires kernel-headers-2.2.10 on all architectures other than hurd-i386 and requires hurd-dev and gnumach-dev only on hurd-i386.

If the architecture-restricted dependency is part of a set of alternatives using |, that alternative is ignored completely on architectures that do not match the restriction. For example:

     Build-Depends: foo [!i386] | bar [!amd64]

is equivalent to bar on the i386 architecture, to foo on the amd64 architecture, and to foo | bar on all other architectures.

Note that the binary package relationship fields such as Depends appear in one of the binary package sections of the control file, whereas the build-time relationships such as Build-Depends appear in the source package section of the control file (which is the first section).

7.2 Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends

Packages can declare in their control file that they have certain relationships to other packages - for example, that they may not be installed at the same time as certain other packages, and/or that they depend on the presence of others.

This is done using the Depends, Pre-Depends, Recommends, Suggests, Enhances, Breaks and Conflicts control file fields.

These seven fields are used to declare a dependency relationship by one package on another. Except for Enhances and Breaks, they appear in the depending (binary) package's control file. (Enhances appears in the recommending package's control file, and Breaks appears in the version of depended-on package which causes the named package to break).

A Depends field takes effect only when a package is to be configured. It does not prevent a package being on the system in an unconfigured state while its dependencies are unsatisfied, and it is possible to replace a package whose dependencies are satisfied and which is properly installed with a different version whose dependencies are not and cannot be satisfied; when this is done the depending package will be left unconfigured (since attempts to configure it will give errors) and will not function properly. If it is necessary, a Pre-Depends field can be used, which has a partial effect even when a package is being unpacked, as explained in detail below. (The other three dependency fields, Recommends, Suggests and Enhances, are only used by the various front-ends to dpkg such as apt-get, aptitude, and dselect.)

For this reason packages in an installation run are usually all unpacked first and all configured later; this gives later versions of packages with dependencies on later versions of other packages the opportunity to have their dependencies satisfied.

In case of circular dependencies, since installation or removal order honoring the dependency order can't be established, dependency loops are broken at some point (based on rules below), and some packages may not be able to rely on their dependencies being present when being installed or removed, depending on which side of the break of the circular dependency loop they happen to be on. If one of the packages in the loop has no postinst script, then the cycle will be broken at that package, so as to ensure that all postinst scripts run with the dependencies properly configured if this is possible. Otherwise the breaking point is arbitrary.

The Depends field thus allows package maintainers to impose an order in which packages should be configured.

The meaning of the five dependency fields is as follows:


This declares an absolute dependency. A package will not be configured unless all of the packages listed in its Depends field have been correctly configured.

The Depends field should be used if the depended-on package is required for the depending package to provide a significant amount of functionality.

The Depends field should also be used if the postinst, prerm or postrm scripts require the package to be present in order to run. Note, however, that the postrm cannot rely on any non-essential packages to be present during the purge phase.


This declares a strong, but not absolute, dependency.

The Recommends field should list packages that would be found together with this one in all but unusual installations.


This is used to declare that one package may be more useful with one or more others. Using this field tells the packaging system and the user that the listed packages are related to this one and can perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable.


This field is similar to Suggests but works in the opposite direction. It is used to declare that a package can enhance the functionality of another package.


This field is like Depends, except that it also forces dpkg to complete installation of the packages named before even starting the installation of the package which declares the pre-dependency, as follows:

When a package declaring a pre-dependency is about to be unpacked the pre-dependency can be satisfied if the depended-on package is either fully configured, or even if the depended-on package(s) are only unpacked or half-configured, provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case, both the previously-configured and currently unpacked or half-configured versions must satisfy any version clause in the Pre-Depends field.

When the package declaring a pre-dependency is about to be configured, the pre-dependency will be treated as a normal Depends, that is, it will be considered satisfied only if the depended-on package has been correctly configured.

Pre-Depends should be used sparingly, preferably only by packages whose premature upgrade or installation would hamper the ability of the system to continue with any upgrade that might be in progress.

Pre-Depends are also required if the preinst script depends on the named package. It is best to avoid this situation if possible.

When selecting which level of dependency to use you should consider how important the depended-on package is to the functionality of the one declaring the dependency. Some packages are composed of components of varying degrees of importance. Such a package should list using Depends the package(s) which are required by the more important components. The other components' requirements may be mentioned as Suggestions or Recommendations, as appropriate to the components' relative importance.

7.3 Packages which break other packages - Breaks

Using Breaks may cause problems for upgrades from older versions of Debian and should not be used until the stable release of Debian supports Breaks.

Ubuntu: Breaks may safely be used in Ubuntu packages, as all supported upgrade paths to current releases involve upgrading dpkg to a version that supports Breaks.

When one binary package declares that it breaks another, dpkg will refuse to allow the package which declares Breaks be installed unless the broken package is deconfigured first, and it will refuse to allow the broken package to be reconfigured.

A package will not be regarded as causing breakage merely because its configuration files are still installed; it must be at least half-installed.

A special exception is made for packages which declare that they break their own package name or a virtual package which they provide (see below): this does not count as a real breakage.

Normally a Breaks entry will have an "earlier than" version clause; such a Breaks is introduced in the version of an (implicit or explicit) dependency which violates an assumption or reveals a bug in earlier versions of the broken package. This use of Breaks will inform higher-level package management tools that broken package must be upgraded before the new one.

If the breaking package also overwrites some files from the older package, it should use Replaces (not Conflicts) to ensure this goes smoothly.

7.4 Conflicting binary packages - Conflicts

When one binary package declares a conflict with another using a Conflicts field, dpkg will refuse to allow them to be installed on the system at the same time.

If one package is to be installed, the other must be removed first - if the package being installed is marked as replacing (see Overwriting files and replacing packages - Replaces, Section 7.6) the one on the system, or the one on the system is marked as deselected, or both packages are marked Essential, then dpkg will automatically remove the package which is causing the conflict, otherwise it will halt the installation of the new package with an error. This mechanism is specifically designed to produce an error when the installed package is Essential, but the new package is not.

A package will not cause a conflict merely because its configuration files are still installed; it must be at least half-installed.

A special exception is made for packages which declare a conflict with their own package name, or with a virtual package which they provide (see below): this does not prevent their installation, and allows a package to conflict with others providing a replacement for it. You use this feature when you want the package in question to be the only package providing some feature.

A Conflicts entry should almost never have an "earlier than" version clause. This would prevent dpkg from upgrading or installing the package which declared such a conflict until the upgrade or removal of the conflicted-with package had been completed. Instead, Breaks may be used.

7.5 Virtual packages - Provides

As well as the names of actual ("concrete") packages, the package relationship fields Depends, Recommends, Suggests, Enhances, Pre-Depends, Breaks, Conflicts, Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep may mention "virtual packages".

A virtual package is one which appears in the Provides control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name everywhere the virtual package name appears. (See also Virtual packages, Section 3.6)

If there are both concrete and virtual packages of the same name, then the dependency may be satisfied (or the conflict caused) by either the concrete package with the name in question or any other concrete package which provides the virtual package with the name in question. This is so that, for example, supposing we have

     Package: foo
     Depends: bar

and someone else releases an enhanced version of the bar package they can say:

     Package: bar-plus
     Provides: bar

and the bar-plus package will now also satisfy the dependency for the foo package.

If a relationship field has a version number attached then only real packages will be considered to see whether the relationship is satisfied (or the prohibition violated, for a conflict or breakage) - it is assumed that a real package which provides the virtual package is not of the "right" version. So, a Provides field may not contain version numbers, and the version number of the concrete package which provides a particular virtual package will not be looked at when considering a dependency on or conflict with the virtual package name.

It is likely that the ability will be added in a future release of dpkg to specify a version number for each virtual package it provides. This feature is not yet present, however, and is expected to be used only infrequently.

If you want to specify which of a set of real packages should be the default to satisfy a particular dependency on a virtual package, you should list the real package as an alternative before the virtual one.

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 file field has these two distinct purposes.

7.6.1 Overwriting files in other packages

Firstly, as mentioned before, 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.

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, Section 6.5. [48]

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

Furthermore, this usage of Replaces only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden.

7.6.2 Replacing whole packages, forcing their removal

Secondly, Replaces allows the packaging system to resolve which package should be removed when there is a conflict - see Conflicting binary packages - Conflicts, Section 7.4. 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:

     Provides: mail-transport-agent
     Conflicts: mail-transport-agent
     Replaces: mail-transport-agent

ensuring that only one MTA can be installed at any one time.

7.7 Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep

Source packages that require certain binary packages to be installed or absent at the time of building the package can declare relationships to those binary packages.

This is done using the Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep control file fields.

Build-dependencies on "build-essential" binary packages can be omitted. Please see Package relationships, Section 4.2 for more information.

The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke the targets in debian/rules, as follows:[49]

Build-Depends, Build-Conflicts

The Build-Depends and Build-Conflicts fields must be satisfied when any of the following targets is invoked: build, clean, binary, binary-arch, build-arch, build-indep and binary-indep.

Build-Depends-Indep, Build-Conflicts-Indep

The Build-Depends-Indep and Build-Conflicts-Indep fields must be satisfied when any of the following targets is invoked: build, build-indep, binary and binary-indep.

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Ubuntu Policy Manual

version, 2009-06-19

The Debian Policy Mailing List
The Ubuntu Developers Mailing List