Check Debian Build Dependencies Before You Build

You will finish with a repeatable pre-flight check for a Debian source package: run dpkg-checkbuilddeps against a control file, interpret success and failure, and choose the dependency fields that match the package you intend to build. The examples use dpkg-checkbuilddeps 1.22.6 from the locally installed dpkg-dev package, version 1.22.6ubuntu6.6.

Allow about fifteen minutes. You need a shell, a Debian-style debian/control file or another control file, and the dpkg-dev package. The checks read the dpkg database and the control file. They do not install, remove or upgrade packages, so the normal workflow does not need elevated privileges.

1. Check the installed command

Confirm which executable is being used and record its version. This is an ordinary, read-only check:

$ command -v dpkg-checkbuilddeps
/usr/bin/dpkg-checkbuilddeps
$ dpkg-checkbuilddeps --version
Debian dpkg-checkbuilddeps version 1.22.6
$ dpkg-query -W -f='${Package} ${Version}\n' dpkg-dev
dpkg-dev 1.22.6ubuntu6.6

Option details and output can vary between dpkg releases. If you are diagnosing a build on another machine, check that machine's version rather than assuming that this guide's output is universal.

2. Run the default check from the source tree

Change to the root of the source package, then run the command without a filename:

$ cd /path/to/source-package
$ dpkg-checkbuilddeps

With no control-file argument, the command reads debian/control. A successful run prints nothing and exits with status 0. Capture that status immediately if a script or a build wrapper needs to use it:

$ dpkg-checkbuilddeps
$ status=$?
$ printf 'dependency check status: %s\n' "$status"
dependency check status: 0

Checkpoint: do not treat silence as a problem. For this command, no output plus status 0 means that the installed packages satisfy the dependencies and do not match the listed build conflicts for the selected build context.

3. Read an unmet dependency failure

A non-zero result means the check found something that does not fit the installed package state. To test the failure path without changing the system, create a small control file in /tmp and ask for a package name that is deliberately unlikely to be installed:

$ control_file=/tmp/example-control
$ printf '%s\n' \
    'Source: example' \
    'Build-Depends: package-that-is-not-installed-anywhere (>= 1)' \
    > "$control_file"
$ dpkg-checkbuilddeps "$control_file"
dpkg-checkbuilddeps: error: Unmet build dependencies: package-that-is-not-installed-anywhere (>= 1)
$ printf 'exit status: %s\n' "$?"
exit status: 1

The package name above is only a test value. Replace it with the real dependency from your project. A non-zero status should stop a build or make its failure visible; it is not a request to install random packages. Resolve the dependency through the project's documented package source, then rerun the check.

The command checks package relationships against the local dpkg database. It does not consult a repository and it does not prove that a later build step will succeed. A package can be installed but still fail a versioned requirement, architecture requirement or other relationship.

4. Check conflicts as well as dependencies

Build conflicts are constraints on packages that must not be installed for the selected build. You can test them independently with -c, which replaces the control file's build-conflict string for this invocation:

$ dpkg-checkbuilddeps -c 'dpkg-dev' "$control_file"
dpkg-checkbuilddeps: error: Build conflicts: dpkg-dev
$ printf 'exit status: %s\n' "$?"
exit status: 1

This fails on the example machine because dpkg-dev is installed. The option does not remove the package and does not edit the control file. It is useful for investigating a generated dependency string, but the normal package check should read the project's declared fields rather than replacing them during a real build.

Do not run a package removal merely to make this check pass. Removing build tools can disrupt other work and is not an undoable diagnostic. Identify why the conflict exists, use the project's supported build environment, or stop and get the package maintainer's guidance.

5. Use an alternate control file safely

The final positional argument names the control file. This lets you inspect a file outside the current directory, which is useful for a packaging review or a generated control file:

$ dpkg-checkbuilddeps /path/to/review/debian/control
$ printf 'exit status: %s\n' "$?"
exit status: 0

Keep the file path quoted if it can contain spaces. The command reads the file; it does not write it. If the path is wrong, fix the path or the source package layout first. Do not create a second control file beside the real one and assume the build will use it: the build tool and this checker can be pointed at different inputs.

6. Match the check to the package being built

Debian control files can separate dependencies for architecture-dependent and architecture-independent work. The default check considers the relevant fields together. Use the switches only when they describe the build you are actually about to perform:

• -A ignores Build-Depends-Arch and Build-Conflicts-Arch. The manual describes this for an architecture-independent-only build, or together with -B for a source-only build.
• -B ignores Build-Depends-Indep and Build-Conflicts-Indep for an architecture-dependent-only build.
• -A -B ignores both specialised groups. It does not make ordinary Build-Depends or Build-Conflicts disappear.
• -I ignores dpkg's built-in build dependencies and conflicts. Use this only when the build environment intentionally provides and checks those requirements elsewhere.

For a package whose host architecture differs from the current system, pass -a with the intended architecture:

$ dpkg-checkbuilddeps -a arm64 /path/to/source-package/debian/control

This changes the assumption used for dependency resolution. It does not turn the current machine into an arm64 build environment.

7. Apply build profiles deliberately

Profile-qualified relationships are selected with -P. Its value is a comma-separated list, such as stage1 or stage1,nocheck:

$ dpkg-checkbuilddeps -P stage1 /path/to/source-package/debian/control
$ printf 'exit status: %s\n' "$?"
exit status: 0

The profile names must match the profiles used by the build. Do not add a profile because it makes an error disappear; that can produce a check that no longer describes the build you will run. The environment variable DEB_BUILD_PROFILES supplies space-separated active profiles when set, and -P overrides it for this command.

When a control file includes profile restrictions, check the exact command line used by the build system. The architecture option, profile option and package database all affect the answer, so record them in reproducible build logs.

8. Override strings only for diagnosis

-d supplies a replacement build-dependency string and -c supplies a replacement build-conflict string. The control file is still required, even when one of these strings is supplied:

$ dpkg-checkbuilddeps -d 'dpkg-dev (>= 1.22.6)' "$control_file"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Use these options to isolate a suspected dependency expression or to reproduce a build tool's input. They do not edit debian/control, and they are easy to misunderstand in a script because they replace the corresponding fields rather than adding to them. Prefer the plain command for the final pre-flight check.