Turn a Source Tree into a .deb with dpkg-buildpackage

Handed an unpacked Debian source tree and told to "just build it", dpkg-buildpackage is the one command that actually does the whole job. It turns that tree into source and binary package artefacts while you keep track of which parts clean the tree and which files get signed. The examples match dpkg-buildpackage 1.22.6 from the installed dpkg-dev package.

Allow about twenty minutes for a first build, plus whatever time the package's declared build dependencies take to install. You need an unpacked Debian source tree containing debian/control, debian/changelog and an executable debian/rules. Run the build as an ordinary user in a writable directory: elevated privileges are normally unnecessary and can leave root-owned files behind.

1. Check the local tool and source tree

Start with read-only checks. This confirms the binary you are about to use and stops you debugging a build launched from the wrong directory:

$ dpkg-buildpackage --version
Debian dpkg-buildpackage version 1.22.6.
$ cd /path/to/unpacked-source
$ test -f debian/control && test -f debian/changelog && test -x debian/rules
$ dpkg-parsechangelog -S Source -S Version
example-package
1.2.3-1

Replace /path/to/unpacked-source with the real directory. The last command only reads package metadata; it builds nothing. If the test line fails, stop and fix the source tree rather than reaching for sudo.

2. Choose the build output deliberately

With no build selection, dpkg-buildpackage defaults to a full build: source, architecture-specific binaries and architecture-independent binaries. Make the choice explicit whenever the result will be uploaded or handed to someone else:

• --build=full builds everything and is the default.
• --build=binary builds both kinds of binary package, but no source package.
• --build=any builds architecture-specific binary packages.
• --build=all builds architecture-independent binary packages.
• --build=source builds the source package only.

The short forms -b, -B, -A, -S, -g and -G select common combinations. For a normal local test, start with a binary build, and leave signing disabled only if you understand the resulting files are not fit for a signed upload.

$ dpkg-buildpackage --help | sed -n '1,35p'
Usage: dpkg-buildpackage [option...]
Options:
  -F           Full build (source and binary)
  -g           Source and architecture-independent binary build
  -G           Source and architecture-specific binary build
  -b           Binary-only build
  -B           Binary-only build, only architecture-specific
  -A           Binary-only build, only architecture-independent
  -S           Source-only build

The help layout can shift slightly between releases. What matters is confirming the selected build form is supported by the version you actually have installed.

3. Build unsigned packages for a local test

Use an unsigned build when your immediate goal is to inspect or test artefacts locally, not ship them:

$ dpkg-buildpackage --build=full --no-sign

By default, dpkg-buildpackage checks build dependencies and conflicts, cleans the source tree before building, runs the package's build targets, creates a .buildinfo file and a .changes file, then leaves the tree without a post-build clean. This is not just a compiler invocation: package hooks and the maintainer's debian/rules drive the whole thing.

Expect output from dpkg-source, debian/rules and the generator tools. A successful run ends with exit status zero, and if you are scripting the build, check it immediately:

$ status=$?
$ printf 'build status: %s\n' "$status"
build status: 0

4. Inspect the generated files

Build outputs land in the parent directory of the source tree. List only the files for the current source package and read the metadata before installing anything:

$ cd ..
$ ls -l example-package_*
$ dpkg-deb --info example-package_1.2.3-1_amd64.deb
$ dpkg-deb --contents example-package_1.2.3-1_amd64.deb | sed -n '1,25p'
$ dpkg-deb --contents example-package_1.2.3-1_amd64.deb | grep -E '(^|/)usr/bin/'

Substitute the actual package and version names; the architecture suffix will differ, and an architecture-independent package ends in all.deb. The .changes file records which files were included in the build, and the .buildinfo records build-environment information. Keep both as evidence when comparing two builds.

Do not install the package just to prove it was built. If a system install is genuinely needed, review the file list and package scripts first, then run your normal package-management change process: installation can change services and system state, which is outside this build workflow.

5. Build a signed result when you have a signing policy

$ dpkg-buildpackage --build=full --sign-key=KEY_FINGERPRINT

KEY_FINGERPRINT is a placeholder, not something to copy literally. The key must be available to the selected OpenPGP backend. You can also use --no-sign for local builds, --unsigned-source for an unsigned .dsc, --unsigned-buildinfo for an unsigned .buildinfo, or --unsigned-changes for unsigned build information and changes files. Each of these changes the trust properties of the output, so record that choice in your build process.

6. Handle dependency and cleanup failures

If the build stops because dependencies are missing, read the diagnostic and install the declared build dependencies through your distribution's normal administration process. --no-check-builddeps is not a general fix: it only skips the check, it does not conjure missing compilers, libraries or tools, so the build usually fails later somewhere less useful.

The default pre-clean runs fakeroot debian/rules clean. It can remove generated files, and it is part of the package's normal build contract. If you need to preserve an in-progress working tree for investigation, stop before retrying and copy or commit your work first. --no-pre-clean skips that clean, but stale generated files can then affect the result, so the safer recovery is usually to return to a known source tree and run the ordinary build again.

To request a clean after a successful build instead, use --post-clean:

$ dpkg-buildpackage --build=binary --no-sign --post-clean

That changes the source tree after the artefacts have already been created, so keep a copy of anything you still need first. There is no universal undo for a maintainer-provided clean target; recovery means restoring the source tree from version control or a backup.

7. Use repeatable build controls only when needed

For a package that supports parallel builds, --jobs=N requests a job count and --jobs-force=N forces parallel operation even where the package does not advertise support. Start with the package's documented setting: forcing parallelism can expose a real or latent race in a build system and can make failures harder to reproduce.

For reproducibility, check the package's changelog and environment as well as the command line. dpkg-buildpackage sets SOURCE_DATE_EPOCH from the latest changelog entry when it is not already set. Environment variables such as DEB_BUILD_OPTIONS and DEB_BUILD_PROFILES can change the result, so record them in CI and compare them when two builds differ.