SBUILD(1)

📦

version 0.91.10ubuntu1 · 10 versions

0.91.10ubuntu1 · ubuntu stonking (latest)
0.88.3ubuntu3.1 · ubuntu questing
0.88.3ubuntu3 · ubuntu questing
0.81.2ubuntu6.1 · ubuntu jammy
0.81.2ubuntu6 · ubuntu jammy
0.85.10ubuntu0.2 · ubuntu noble
0.85.7 · ubuntu noble
0.85.0 · debian bookworm
0.91.2ubuntu3 · ubuntu resolute
0.89.3 · debian trixie

💅 SBUILD — the Debian sbuild manual, bestie edition ✨

okay so you're here because you want to build Debian packages from source, and sbuild is the girl for the job. Welcome to the Debian sbuild manual, rewritten for your reading pleasure 🫶

👑 NAME

sbuild — build debian packages from source ✨

🌸 SYNOPSIS

sbuild [-h|--help | -V|--version] [-v|--verbose | -q|--quiet]
[-D|--debug] [-A|--arch-all] [--archive=archive]
[-d|--dist=distribution] [-c|--chroot=chroot]
[--chroot-mode=schroot|sudo|autopkgtest|unshare] [--arch=architecture]
[--arch-any | --no-arch-any] [--build=architecture]
[--host=architecture] [--profiles=profile[,...]]  [-s|--source]
[--force-orig-source] [--make-binNMU=changelog-entry] [--binNMU=NMU-
version] [--append-to-version=string] [--binNMU-timestamp=timestamp]
[--binNMU-changelog=changelog] [--build-dir=directory]
[--add-depends=dependency] [--add-conflicts=dependency]
[--add-depends-arch=dependency] [--add-conflicts-arch=dependency]
[--add-depends-indep=dependency] [--add-conflicts-indep=dependency]
[-m|--maintainer=maintainer] [-e|--uploader=uploader] [-k|--keyid=key-
id] [--source-only-changes] [--no-source-only-changes] [-j|--jobs=n]
[--enable-network] [--no-enable-network] [--debbuildopt=option]
[--debbuildopts=options] [--dpkg-source-opt=options]
[--dpkg-source-opts=options] [--dpkg-file-suffix=suffix]
[-p|--purge=purge-mode] [--purge-build=purge-mode] [--purge-deps=purge-
mode] [--purge-session=purge-mode] [-b|--batch] [-n|--nolog] [--hide-
log-sections=sections] [--clean-source] [--no-clean-source]
[--run-lintian] [--no-run-lintian] [--lintian-opt=options]
[--lintian-opts=options] [--run-piuparts] [--no-run-piuparts]
[--piuparts-opt=options] [--piuparts-opts=options]
[--piuparts-root-arg=options] [--piuparts-root-args=options]
[--run-autopkgtest] [--no-run-autopkgtest] [--autopkgtest-opt=options]
[--autopkgtest-opts=options] [--autopkgtest-root-arg=options]
[--autopkgtest-root-args=options] [--pre-build-commands=string]
[--chroot-setup-commands=string]
[--chroot-update-failed-commands=string]
[--build-deps-failed-commands=string] [--starting-build-commands=string]
[--finished-build-commands=string] [--build-failed-commands=string]
[--chroot-cleanup-commands=string] [--post-build-commands=string]
[--post-build-failed-commands=string]
[--anything-failed-commands=string] [--log-external-command-output]
[--log-external-command-error] [--setup-hook=hook-script]
[--build-dep-resolver=resolver]
[--resolve-alternatives|--no-resolve-alternatives]
[--extra-package=package.deb|directory] [--extra-repository=spec]
[--extra-repository-key=file.asc] [--build-path=string]
[--dsc-dir=string] [--autopkgtest-virt-server=string]
[--autopkgtest-virt-server-opt=string]
[--autopkgtest-virt-server-opts=options] [--purge-extra-packages]
[--bd-uninstallable-explainer=dose3|apt|none] [PACKAGE[.dsc]]

🦋 DESCRIPTION

so basically 💖 sbuild rebuilds Debian binary packages from the corresponding Debian source, and it installs any missing source dependencies for you. no cap. The build happens inside a dedicated clean build environment, not on your host system — which is the whole point, bestie. If you wanna know about all the chroot backends it supports, go peek at the section CHROOT MODES 👀

sbuild can fetch the Debian source over a network 🌐, or it can use sources you already have locally. Your call.

You hand sbuild stuff to process via the argument PACKAGE[.dsc]. That argument can be any of these:

a debianized package source directory,
a source package name plus a version, in the form package_version,
a source package name,
or a .dsc file.

And if you give it no arguments at all? Then the current working directory gets passed as the argument. iconic default behaviour honestly 🎀

Here's the tea on how each argument type gets handled ☕:

For arguments given as source directories, dpkg-source is first run to produce a source .dsc file. Then the package is built using the .dsc produced.
For arguments in the form package_version or package, apt is used to download the source package.
For arguments given as a .dsc file, sbuild builds the source packages directly.
For .dsc files in remote locations, the source packages are downloaded first, then built.

It's also possible to run external commands with sbuild. See EXTERNAL COMMANDS for more on that. 🔥

sbuild mails the build logs to a user 📬. It gets configured by the configuration files /etc/sbuild/sbuild.conf and $XDG_CONFIG_HOME/sbuild/config.pl (which is preferred over ~/.sbuildrc). If $XDG_CONFIG_HOME is either not set or empty, ~/.config/sbuild/config.pl will be used instead. An example sbuildrc is available in /usr/share/doc/sbuild/examples/example.sbuildrc. And if you want a custom config path? Just set the SBUILD_CONFIG environment variable to the path of an additional configuration file. slay 💅

You can build either using a local package with its .dsc file, or a remote one by specifying an explicit dpkg version. simple as that ✨

✨ OPTIONS ✨

heads up bestie: options set on the command line overwrite settings made in the configuration file. command line eats first, periodt 💅

-h, --help — Display this manual. 📖
-V, --version — Print version information. 🏷️
--add-depends=dependency
--add-conflicts=dependency
--add-depends-arch=dependency
--add-conflicts-arch=dependency
--add-depends-indep=dependency
--add-conflicts-indep=dependency

These options add a build dependency to the source package being built, on top of the build dependency info already specified in debian/control. These dependencies get concatenated directly to Build-Depends, Build-Conflicts, Build-Depends-Arch, Build-Conflicts-Arch, Build-Depends-Indep and Build-Conflicts-Indep respectively. You can use these options any number of times to stack up multiple dependencies 🔥. The format is identical to the format used in debian/control. These command line options append to the MANUAL_DEPENDS, MANUAL_CONFLICTS, MANUAL_DEPENDS_ARCH, MANUAL_CONFLICTS_ARCH, MANUAL_DEPENDS_INDEP and MANUAL_CONFLICTS_INDEP configuration variables, respectively. See sbuild.conf(5) for more information. 🫶

--arch=architecture — Build using the architecture specified. A chroot named $distribution-$arch-sbuild or $distribution-arch is searched for, in that order of preference. The chroot must be installed and configured appropriately to build as that architecture, e.g. using personality=linux32 to build i386 packages on an amd64 system. Note that this option is equivalent to --host=architecture --build=architecture. If you specify an architecture that your CPU cannot execute, make sure that you have qemu-user with binfmt support installed to emulate the foreign architecture 🧚. Since build and host architecture are equivalent, this option will result in a native compilation, even if the native compilation is being emulated transparently using qemu. This command line option sets the HOST_ARCH and BUILD_ARCH configuration variables. See sbuild.conf(5) for more information.
--host=architecture — Build using the host architecture specified. Defaults to the native architecture. The host architecture is the architecture that sbuild will build packages for. If the specified architecture is different from the build architecture, then a cross-build is being performed 👀. If $host and $build don't match, a chroot named $distribution-$build-$host-sbuild or $distribution-$build-$host is searched for, falling back to $distribution-$build-sbuild or $distribution-$build, in that order of preference. This command line option sets the HOST_ARCH configuration variable. See sbuild.conf(5) for more information.
--build=architecture — Build using the build architecture specified. Defaults to the native architecture. The build architecture is the architecture of the chroot that the package will be built in. If you want to perform a native build, set the host architecture to the same value or just use the --arch option. This command line option sets the BUILD_ARCH configuration variable. See sbuild.conf(5) for more information.
-A, --arch-all — Also build Architecture: all packages. This is the default behaviour for native builds. This option is the opposite of --no-arch-all. See the section BUILD ARTIFACTS for more information. This command line option sets the BUILD_ARCH_ALL configuration variable. See sbuild.conf(5) for more information.
--no-arch-all — Do not build Architecture: all packages. This is the default behaviour for cross builds. This option is the opposite of --arch-all. See the section BUILD ARTIFACTS for more information. This command line option sets the BUILD_ARCH_ALL configuration variable. See sbuild.conf(5) for more information.
--arch-any — Build Architecture: any packages. This is the default behavior. This option is the opposite of --no-arch-any. See the section BUILD ARTIFACTS for more information. This command line option sets the BUILD_ARCH_ANY configuration variable. See sbuild.conf(5) for more information.
--no-arch-any — Do not build Architecture: any packages. This option is the opposite of --arch-any and only useful when used together with --arch-all or --source. See the section BUILD ARTIFACTS for more information. This command line option sets the BUILD_ARCH_ANY configuration variable. See sbuild.conf(5) for more information.
-b, --batch — Operate in batchmode, i.e. write a build-progress file during execution and files on shutdown to facilitate a clean restart 😌. This command line option sets the BATCH_MODE configuration variable. See sbuild.conf(5) for more information.
-c, --chroot=chroot — okay so this one tells sbuild which chroot to use, but bestie, what that even means depends entirely on which chroot mode you're in. Buckle up:
- schroot mode: this is the schroot name or alias you want. Don't specify it and sbuild defaults to the first schroot name or alias that actually exists, checking in this order: $distribution-$arch-sbuild, $distribution-sbuild, $distribution-$arch, then $distribution.
- sudo mode: now it's the chroot directory to use. That directory is expected either in /etc/sbuild/chroot (when you're in buildd sbuild mode) or in the build directory (see --build-dir), prefixed with chroot- (this is user sbuild mode, which is the default). Leave it unspecified and sbuild searches for a directory in those respective locations, named the exact same way as the schroot mode naming above.
- unshare mode: if the value is a path, that's the location of the chroot tarball, directly, no middleman. Otherwise, a tarball with an equal basename from ~/.cache/sbuild gets used. Unspecified? sbuild searches for a tarball named the schroot-mode way under ~/.cache/sbuild.
- autopkgtest mode: this option literally does nothing here 💀. The --autopkgtest-virt-server-opts are what pick the chroot in autopkgtest mode.

This command line option sets the CHROOT configuration variable. See sbuild.conf(5) for more information.

--chroot-mode=schroot|sudo|autopkgtest|unshare — pick your chroot mode, four choices on the menu: schroot (the default, the classic), sudo (which uses sudo to execute chroot in a directory from /etc/sbuild/chroot or ./chroot), autopkgtest which uses the autopkgtest-virt-* binaries (selectable via the --autopkgtest-virt-server option), and unshare (which uses linux namespaces for chroot and doesn't require superuser privileges — yes, no root, iconic). See the section CHROOT MODES for more information. This command line option sets the CHROOT_MODE configuration variable. See sbuild.conf(5) for more information.
-d, --dist=distribution — explicitly set the distribution for the package build. This selects the correct chroot to use and sets the value of the Distribution field in the created .changes file. You kinda need this when you hand sbuild a .dsc file or a plain source package name to build. In that second case it's the distribution the source package gets fetched from. This command line option sets the DISTRIBUTION configuration variable. See sbuild.conf(5) for more information.
--archive=archive — communicate with the specified archive. Talk to it. Gossip with it. This command line option sets the ARCHIVE configuration variable. See sbuild.conf(5) for more information.
-D, --debug — enable debug output. Turn the volume up on the logs 🔊.
--apt-clean, --no-apt-clean — run (or do not run) apt-get clean in the chroot before executing the build, overriding the default setting. This command line option sets the APT_CLEAN configuration variable. See sbuild.conf(5) for more information.
--apt-update, --no-apt-update — run (or do not run) apt-get update in the chroot before executing the build. This only applies to the default repositories of the chroot: the internal sbuild apt repository, the repository for extra packages (see --extra-package) and any repositories set via --extra-repository are always updated, no exceptions.

It is not recommended to use --no-apt-update because you should build using the latest available packages in each distribution. If you do disable updates you need to ensure that the chroot contains downloaded package lists or apt will be unable to install any packages and the build is likely to fail. If you are using the unshare chroot mode you can add --skip=cleanup/apt/lists to $unshare_mmdebstrap_extra_args to retain the package lists inside the chroot tarball.

This command line option sets the APT_UPDATE configuration variable. See sbuild.conf(5) for more information.

--apt-upgrade, --no-apt-upgrade — run (or do not run) apt-get upgrade in the chroot before executing the build, overriding the default setting. This command line option sets the APT_UPGRADE configuration variable. See sbuild.conf(5) for more information.
--apt-distupgrade, --no-apt-distupgrade — run (or do not run) apt-get distupgrade in the chroot before executing the build, overriding the default setting. This command line option sets the APT_DISTUPGRADE configuration variable. See sbuild.conf(5) for more information.
-m, --maintainer=maintainer — specify the identity used for GPG signing packages, and also used as the maintainer for binary NMUs. You don't normally need to set this (it defaults to the uploader). This command line option sets the MAINTAINER_NAME configuration variable. See sbuild.conf(5) for more information.
-e, --uploader=uploader — passed to dpkg-genchanges and used to set the Changed-by: field in the .changes file(s). This command line option sets the UPLOADER_NAME configuration variable. See sbuild.conf(5) for more information.
-k, --keyid=key-id — passed to debsign and used to set the key for signing the .changes file(s). Default is not using any key and not signing the .changes file(s) — so the default is just vibes, unsigned. This command line option sets the KEY_ID configuration variable. See sbuild.conf(5) for more information.
--source-only-changes, --no-source-only-changes — in addition to the .changes file generated by dpkg-buildpackage, also produce (or don't produce) a .changes file suitable for a source-only upload. If requested by --keyid, this .changes file will also be signed by debsign. This command line option sets the SOURCE_ONLY_CHANGES configuration variable. See sbuild.conf(5) for more information.
-j, --jobs=n — number of jobs to run simultaneously. Passed through to dpkg-buildpackage. Parallelism, we love to see it ✨. This command line option appends the appropriate -j option to the DPKG_BUILDPACKAGE_USER_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--enable-network — enable network access during build. This command line option sets the ENABLE_NETWORK configuration variable. See sbuild.conf(5) for more information.
--no-enable-network — don't enable network access during build (only implemented for the unshare mode) (this is the default). This command line option sets the ENABLE_NETWORK configuration variable. See sbuild.conf(5) for more information.
--debbuildopt=option — pass the specified option directly to dpkg-buildpackage in addition to the options already passed by sbuild. You can pass this multiple times (once per dpkg-buildpackage option) and freely mix it with the --debbuildopts option. Options get passed to dpkg-buildpackage in the order that the --debbuildopt and --debbuildopts options are given on the command line. This command line option appends to the DPKG_BUILDPACKAGE_USER_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--debbuildopts=options — pass the specified options directly to dpkg-buildpackage in addition to the options already passed by sbuild. The argument gets split by whitespaces and the resulting array is passed to the dpkg-buildpackage invocation. If any options contain spaces, use --debbuildopt for them instead. You can pass this multiple times and freely mix it with the --debbuildopt option. Options get passed to dpkg-buildpackage in the order that the --debbuildopt and --debbuildopts options are given on the command line. This command line option appends to the DPKG_BUILDPACKAGE_USER_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--dpkg-source-opt=options — pass the specified option directly to dpkg-source in addition to the options already passed by sbuild. This is only used when creating a source package from a Debianized source directory. You can pass this multiple times (once per dpkg-source option) and freely mix it with the --dpkg-source-opts option. Options get passed to dpkg-source in the order that the --dpkg-source-opt and --dpkg-source-opts options are given on the command line. This command line option appends to the DPKG_SOURCE_OPTIONS configuration variable. See sbuild.conf(5) for more information.

NOTE: The -b, --before-build and --after-build options will always be passed to dpkg-source, respectively.

--dpkg-source-opts=options — pass the specified options directly to dpkg-source in addition to the options already passed by sbuild. The argument gets split by whitespaces and the resulting array is passed to the dpkg-source invocation. This is only used when creating a source package from a Debianized source directory. If any options contain spaces, use --dpkg-source-opt for them instead. You can pass this multiple times and freely mix it with the --dpkg-source-opt option. Options get passed to dpkg-source in the order that the --dpkg-source-opt and --dpkg-source-opts options are given on the command line. This command line option appends to the DPKG_SOURCE_OPTIONS configuration variable. See sbuild.conf(5) for more information.

NOTE: The -b, --before-build and --after-build options will always be passed to dpkg-source, respectively.

--dpkg-file-suffix=suffix — add the suffix to the filename of the changes and buildinfo files generated by dpkg. Cute little name tag for your files 🎀.

NOTE: This option is ignored if dpkg-dev in the build environment is too old to support it. At least dpkg-dev 1.18.11 is required.

--mail-log-to=email-address — send the build log to the specified email address. This command line option sets the MAILTO configuration variable. See sbuild.conf(5) for more information.
--mailfrom=email-address — email address used as the sender address for build logs. This command line option sets the MAILFROM configuration variable. See sbuild.conf(5) for more information.
-n, --nolog — bestie, this one is the anti-log. No package log file in $log_dir, no build log file, nope, nada, not a single one 💀 everything just gets printed straight to stdout instead. And no log mails either, we're not emailing anybody. This sets the NOLOG config variable. Peep sbuild.conf(5) for the deets.
--hide-log-sections=section1,section2,... — hides specific log sections from standard output so your terminal isn't giving chaos energy. The section names you're allowed to hide are: postbuild, cleanup, changes, buildinfo, contents and summary. Separate multiple names with commas, and yes you can pass this option multiple times. This sets the LOG_HIDDEN_SECTIONS config variable. sbuild.conf(5) has more.
--log-filename-ts-format=format — sets the format of the timestamp in the build log filename, using the same format as strftime. Customize your filenames, slay ✨
--profiles=profile[,...] — tells sbuild which profile(s) we're building, comma-separated list style. Defaults to the space-separated list of profiles in the DEB_BUILD_PROFILES environment variable when building natively, or the cross and nocheck profiles when cross-building. This sets the BUILD_PROFILES config variable. sbuild.conf(5), you know the drill.
-p, --purge=purge-mode — the convenience queen 👑 sets purge-mode for the build directory, the build dependencies and the session, all in one go. It sets the PURGE_BUILD_DEPS, PURGE_BUILD_DIRECTORY and PURGE_SESSION config variables all at once. sbuild.conf(5) for more.
--purge-build=purge-mode — does the build directory get deleted after a build or not? purge-mode decides. Possible values are always (the default), never, and successful. Sets the PURGE_BUILD_DIRECTORY config variable. sbuild.conf(5) babes.
--purge-deps=purge-mode — same energy but for the build dependencies: do they get removed after a build? Possible values are always (default), never, and successful. Sets the PURGE_BUILD_DEPS config variable. sbuild.conf(5).
--purge-session=purge-mode — purges the schroot session after a build. This one is lowkey a baddie when you pair it with the --purge-build and --purge-deps options and you're using snapshot chroots, because by default that snapshot will get deleted. Possible values are always (default), never, and successful. Sets the PURGE_SESSION config variable. sbuild.conf(5) has the tea.
-s, --source — builds the source package on top of the other build artifacts you asked for. By default the dsc will not be rewritten, because the source package is the input to sbuild, not its output. Even when you run it from an unpacked source tree, sbuild will first build the source package using dpkg-source and then hand that off to the sbuild machinery. Use this option only when you know what you are doing — it will rewrite the original dsc you passed to sbuild 😭 See the BUILD ARTIFACTS section for more. Sets the BUILD_SOURCE config variable. sbuild.conf(5).
--no-source — don't rebuild the source package. This is the default, and it's the opposite of --source. See the BUILD ARTIFACTS section. Sets the BUILD_SOURCE config variable. sbuild.conf(5).
--force-orig-source — when used together with -s, this forces the inclusion of the orig.tar.gz file in the generated .changes file, even in cases where it wouldn't normally be included, i.e. dpkg-buildpackage -sa energy. Sets the FORCE_ORIG_SOURCE config variable. sbuild.conf(5) for more.
--use-snapshot — installs the latest snapshot gcc compiler from the gcc-snapshot package and alters the build environment to use that snapshot compiler for the build. Specifically, it appends /usr/lib/gcc-snapshot/lib to the value of the LD_LIBRARY_PATH config variable and /usr/lib/gcc-snapshot/bin to the value of the PATH config variable. It also sets the GCC_SNAPSHOT config variable. sbuild.conf(5) if you want more.
-v, --verbose — be verbose, i.e. all the information goes to stdout as well as to the log files. Spill the tea everywhere 💅
-q, --quiet — be quiet. This is the opposite of --verbose. Not a peep 🤫
--make-binNMU=changelog-entry — with this one, sbuild creates a brand new changelog entry in debian/changelog of every package built. The version number will be in the format for binary-only NMUs (peep --binNMU); the maintainer is set to the maintainer name configured for sbuild. changelog-entry will be used as the changelog entry following “Binary-only non-maintainer upload for ARCH -- no source changes”. Heads up bestie: the versions in the PACKAGE_VERSION[.dsc] arguments still have to be the unmodified (non-NMU) ones so the sources can actually be found. The version number in log files and mails will get modified by sbuild automatically. The --append-to-version option has a similar effect but lets you specify an arbitrary version suffix instead of a custom changelog entry. If you want a custom version suffix and a custom changelog entry, use --make-binNMU and --append-to-version at the same time with --binNMU=0. This option is incompatible with --binNMU-changelog. It implies --no-arch-all. This sets the BIN_NMU config variable and sets the BIN_NMU_VERSION config variable to 1 if it wasn't set yet, for example by the --binNMU option. sbuild.conf(5) for more.
--binNMU=NMU-version — the version number of the binary NMU. This option only does anything if it's combined with --make-binNMU and/or with --append-to-version. version is a single number for the (+bn) format used for binary NMUs. If the argument is the empty string or zero, then the +bn suffix will not be appended. The +bn suffix gets appended after the string given via --append-to-version. This option is incompatible with --binNMU-changelog. Sets the BIN_NMU_VERSION config variable. sbuild.conf(5) for more.
--append-to-version=string — similar to --make-binNMU except it lets you specify an arbitrary string to be appended to the version number (immediately before the + in the Debian revision, if --make-binNMU is also provided). To pass an arbitrary changelog text as well, combine this option with --make-binNMU, but be aware that this will also add the +bn suffix unless you also pass --binNMU=0 to disable it 🙈 This option is incompatible with --binNMU-changelog. It implies --no-arch-all. Sets the APPEND_TO_VERSION config variable. sbuild.conf(5).
--binNMU-timestamp=timestamp — sets the timestamp of the new binNMU changelog entry. By default the time of the build is used to generate the binNMU changelog timestamp, but this option lets you use a custom one instead. The timestamp is either an integer in Unix time, or a string in the format compatible with Debian changelog entries (i.e. as generated by date -R). This option is incompatible with --binNMU-changelog. Sets the BIN_NMU_TIMESTAMP config variable. sbuild.conf(5).
--binNMU-changelog=changelog — sets the complete content of a binary-only changelog entry, so you get full customization of the new changelog entry. It's up to you to make sure the changelog entry is well-formed, no pressure 😅 The argument has to include all necessary newlines. Leading and trailing newlines will be stripped. Sbuild will not interpret any backslash escapes. This option is incompatible with --make-binNMU, --binNMU, --append-to-version and --binNMU-timestamp. Sets the BIN_NMU_CHANGELOG config variable. sbuild.conf(5).
--build-dir=directory — sets the output directory for the build artifacts created by dpkg-buildpackage and the log file. By default the current directory is used, or — when sbuild is executed from within an unpacked source directory — the parent directory. Sets the BUILD_DIR config variable. sbuild.conf(5) if you want more.
--clean-source — when executing sbuild from within an unpacked source tree, this executes the debian/rules clean target. This is the default, and it might require some of the build dependencies installed on the host. Sets the CLEAN_SOURCE config variable. sbuild.conf(5).
--no-clean-source — when executing sbuild from within an unpacked source tree, this does not run the debian/rules clean target before building the source package. Only set this if you start from a clean checkout and you know what you are doing ⚠️ Sets the CLEAN_SOURCE config variable. sbuild.conf(5).
--run-lintian — runs lintian after a successful build. Sets the RUN_LINTIAN config variable. sbuild.conf(5) for more.
--no-run-lintian — doesn't run lintian after a successful build. If sbuild is configured to run lintian by default, this option will prevent lintian from being run at all. Sets the RUN_LINTIAN config variable. sbuild.conf(5).

--lintian-opt=options — okay so this one yeets your option directly at lintian, on top of all the options sbuild already hands over, bestie 💅. Pass it as many times as you want (like, once per lintian option, no cap) and mix it freely with --lintian-opts, they don't fight 🫶. The order they land on the command line? That's literally the order lintian gets them in ✨. This one appends to the LINTIAN_OPTIONS configuration variable. Go read sbuild.conf(5) for the tea 👑
--lintian-opts=options — same energy, except the argument gets split on whitespaces first and the resulting array gets passed to the lintian invocation 🌸. So if any of your options have spaces in them, use --lintian-opt for those instead, fr fr. Pass it multiple times, mix it freely with the --lintian-opts option, and order stays exactly as given on the command line 💖. This one also appends to the LINTIAN_OPTIONS configuration variable. sbuild.conf(5) has the deets 📖
--run-piuparts — run piuparts after a successful build 🎀. Yes queen, extra testing. This sets the RUN_PIUPARTS configuration variable. sbuild.conf(5) for more 💜
--no-run-piuparts — don't run piuparts after a successful build 🙈. If your sbuild is configured to run piuparts by default, this here is the veto — piuparts will not run. This sets the RUN_PIUPARTS configuration variable. sbuild.conf(5), you know the drill 💅
--piuparts-opt=options — passes the option straight to piuparts, directly, on top of whatever sbuild already sends 🦋. Multiple times? Absolutely. Mixed with --piuparts-opts? Freely. Order given on the command line = order piuparts receives them ✨. Certain percent escapes are supported in here, and to write a literal percent sign you escape it with another percent sign (the drama of it all 😭) — see the OPTION STRING PERCENT ESCAPES section. This one appends to the PIUPARTS_OPTIONS configuration variable. sbuild.conf(5) 🌈
--piuparts-opts=options — same vibe, but the argument gets split by whitespaces and the array goes to the piuparts invocation 🌸. Options with spaces in them? Use --piuparts-opt for those, bestie. Pass it multiple times, mix freely with --piuparts-opts, order preserved like a queen 👑. Certain percent escapes are supported, and a literal percent sign needs another percent sign as its escape — see OPTION STRING PERCENT ESCAPES. This one appends to the PIUPARTS_OPTIONS configuration variable. sbuild.conf(5) 💖
--piuparts-root-arg=options — adds an argument used to launch piuparts as root 💅. Without it, the default is to use "sudo --" to launch piuparts. Supply an empty string and piuparts is launched with no prefixed command at all — iconic, unbothered, no middleman ✨. Can be specified multiple times. This one appends to the PIUPARTS_ROOT_ARGS configuration variable. sbuild.conf(5) 🎀
--piuparts-root-args=options — adds arguments used to launch piuparts as root 🫶. Without it, default is "sudo --" to launch piuparts; empty string means no prefixed command whatsoever. The argument gets split by whitespaces, so to pass options that contain whitespaces use --piuparts-root-arg instead, okay? This one appends to the PIUPARTS_ROOT_ARGS configuration variable. sbuild.conf(5) 💜
--run-autopkgtest — run autopkgtest after a successful build 🔥. This sets the RUN_AUTOPKGTEST configuration variable. sbuild.conf(5) for the full story 🦋
--no-run-autopkgtest — don't run autopkgtest after a successful build 🙈. If sbuild is configured to run autopkgtest by default, this right here stops it in its tracks. This sets the RUN_AUTOPKGTEST configuration variable. sbuild.conf(5) 😌
--autopkgtest-opt=options — tosses the option directly at autopkgtest, on top of the ones sbuild already passes 🌸. Multiple times (once per autopkgtest option), freely mixed with --autopkgtest-opts, and the order on the command line is exactly the order autopkgtest sees them in ✨. Certain percent escapes are supported — literal percent sign? Escape it with another percent sign. See OPTION STRING PERCENT ESCAPES. This one appends to the AUTOPKGTEST_OPTIONS configuration variable. sbuild.conf(5) 💖
--autopkgtest-opts=options — argument gets split by whitespaces, resulting array goes to the autopkgtest invocation 🎀. Options containing spaces belong in --autopkgtest-opt, not here, bestie. Pass multiple times, mix freely with --autopkgtest-opts, order preserved 👑. Certain percent escapes are supported; write a literal percent sign by escaping it with another percent sign. See OPTION STRING PERCENT ESCAPES. This one appends to the AUTOPKGTEST_OPTIONS configuration variable. sbuild.conf(5) 🌈
--autopkgtest-root-arg=options — adds an argument used to launch autopkgtest as root 💅. Without it, default = "sudo --" to launch autopkgtest. Empty string = autopkgtest launches with no prefixed command, periodt ✨. Can be specified multiple times. This one appends to the AUTOPKGTEST_ROOT_ARGS configuration variable. sbuild.conf(5) 🫶
--autopkgtest-root-args=options — adds arguments used to launch autopkgtest as root 🌸. Without it, default = "sudo --" to launch autopkgtest; empty string = no prefixed command. The argument gets split by whitespaces, so for options with whitespaces use --autopkgtest-root-arg instead. This one appends to the AUTOPKGTEST_ROOT_ARGS configuration variable. sbuild.conf(5) 💜

lowkey this next batch is the external-commands squad, and they are so useful when stuff goes sideways 😭. Obsessed.

--pre-build-commands=string — this is the earliest external command, running right after the chroot session has been initialized and before literally anything else happens (yes, before installing the build dependencies) 🔥. It runs outside of the chroot. Can be used multiple times to add multiple commands. Certain percent escapes are supported — literal percent sign, escape it with another percent sign. See the EXTERNAL COMMANDS section for the full lore. This one appends to the EXTERNAL_COMMANDS configuration variable. sbuild.conf(5) ✨
--chroot-setup-commands=string — runs these commands after the chroot and variables have been set up, but before dependencies get installed 🎀. This one runs as root inside the chroot. Can be used multiple times to stack up commands. Certain percent escapes supported; a literal percent sign needs another percent sign to escape it. See EXTERNAL COMMANDS. This one appends to the EXTERNAL_COMMANDS configuration variable. sbuild.conf(5) 💖
--chroot-update-failed-commands=string — these run after any of 'apt-get update', 'apt-get upgrade' or 'apt-get dist-upgrade' failed 😭. Important caveat, bestie: this hook does not run for updates of the internal sbuild apt repository, the repository for extra packages (see --extra-package) and the repositories given via --extra-repository. The environment is intact and the failure can be investigated — and especially %SBUILD_SHELL is useful here 👑. Can be used multiple times to add multiple commands. Certain percent escapes are supported; to write a literal percent sign, escape it with another percent sign. See the EXTERNAL COMMANDS section for more. This one appends to the EXTERNAL_COMMANDS configuration variable. sbuild.conf(5) 💜
--build-deps-failed-commands=string — these commands run if installing the build dependencies has failed, directly after the failed attempt 🙈. The environment is intact, so you can actually go investigate the mess — and especially %SBUILD_SHELL is useful here 💅. The command runs as root inside the chroot. Can be used multiple times to add multiple commands. Certain percent escapes are supported; to write a literal percent sign, escape it with another percent sign. See the EXTERNAL COMMANDS section. This one appends to the EXTERNAL_COMMANDS configuration variable. sbuild.conf(5) 🦋
--starting-build-commands=string — bestie, these are the commands that get run right after your dependencies are installed and just before the actual package build with dpkg-buildpackage kicks off. They run as the root user inside the chroot (yes, root root 👑). Drop this flag multiple times to stack up multiple commands. Certain percent escapes are supported — and if you want a literal percent sign, escape it with another percent sign (yeah, %%, it's giving very "escape the escape chased the escape" energy 🙈). Peep the EXTERNAL COMMANDS section for the deets. This flag appends to the EXTERNAL_COMMANDS configuration variable, so go read sbuild.conf(5) if you want more.
--finished-build-commands=string — run these immediately after the timed package build finishes. Also run as the root user inside the chroot. Also stackable (hit it multiple times, add as many commands as your heart desires 💖). Also supports those percent escapes, and yes, literal percent sign = escape it with another percent sign. See EXTERNAL COMMANDS for more. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--build-failed-commands=string — these ones run if dpkg-buildpackage has failed, directly after that failed attempt 😭. The environment is left intact, meaning you can actually go investigate what went wrong — and ngl, %SBUILD_SHELL is especially useful here (it's the moment, fr). Runs as the root user inside the chroot. Use it multiple times for multiple commands. Percent escapes supported; literal percent sign gets escaped with another percent sign. See the EXTERNAL COMMANDS section. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--chroot-cleanup-commands=string — these run when a chroot gets cleaned up, and importantly, before the build directory is purged 🧹✨. Run as root inside the chroot. Multiple uses = multiple commands. Percent escapes supported; literal percent sign → escape it with another percent sign. EXTERNAL COMMANDS section has the lore. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--post-build-commands=string — these run after a successful build 🎉 and they run outside of the chroot (plot twist, bestie — not inside this time). Hit it multiple times to add multiple commands. Percent escapes supported; literal percent sign gets escaped with another percent sign. See the section EXTERNAL COMMANDS for more info. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--post-build-failed-commands=string — exactly like the one above, but when a build fails 💀. See the EXTERNAL COMMANDS section for more information. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--anything-failed-commands=string — the catch-all queen 👑: these run for all the --xxx-failed-commands options. And once again, %SBUILD_SHELL is especially useful here. Multiple uses = multiple commands. Percent escapes supported; literal percent sign gets escaped with another percent sign. See the EXTERNAL COMMANDS section. This flag appends to EXTERNAL_COMMANDS. See sbuild.conf(5) for more.
--log-external-command-output — write the output from external commands straight into the build log 📝. This flag sets the LOG_EXTERNAL_COMMAND_OUTPUT configuration variable. See sbuild.conf(5) for more.
--log-external-command-error — same vibe, but for the error output from external commands, also into the build log. This flag sets the LOG_EXTERNAL_COMMAND_ERROR configuration variable. See sbuild.conf(5) for more.
--setup-hook=hook-script DEPRECATED — okay so this option is deprecated, like, do not build your whole personality around it bestie 😭. Using it will add hook-script to the external commands that get run via chroot-setup-commands. This flag sets the CHROOT_SETUP_SCRIPT configuration variable and appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5) for more.
--build-dep-resolver=resolver — pick which resolver handles selecting your build dependencies. Supported resolvers are apt (the default ✨), aptitude, aspcud, xapt, and null. Let's break it down 🫶:
- apt — the most appropriate resolver for most users, for building for unstable, stable and other distributions. Heads up: if alternative build dependencies are used (excluding architecture restrictions), only the first alternative will be used and the others get ignored 🙈.
- aptitude — very similar, but smarter and slower 💅, and it will consider all alternatives by default. Suited to more complex situations, like building packages for the experimental distribution where packages need installing from multiple suites (unstable and experimental). Due to performance issues, it's not recommended for use by default.
- aspcud — for when the dependency situation is so complex that neither apt nor aptitude can find a solution. It uses apt-cudf to ask aspcud, a real solver (and we mean solver in the math sense 🧮), to find a solution to the installation problem. Since aspcud uses a real solver (an ASP solver), it will always find a solution if one exists. You can refine the solution it finds by changing the default optimization criteria through the --aspcud-criteria option.
- xapt — intended only for cross-building, and it's a temporary transitional feature which will be removed following the complete introduction of multi-arch support. So like, don't get attached 🥲.
- null — a dummy solver that does not install, upgrade or remove any packages. This lets you completely control package installation via hooks.

This flag sets the BUILD_DEP_RESOLVER configuration variable. See sbuild.conf(5) for more.

--aspcud-criteria=criteria — optimization criteria in extended MISC 2012 syntax passed to aspcud through apt-cudf. Criteria are separated by commas, sorted by decreasing order of priority, and prefixed with a polarity (+ to maximize and - to minimize). The default criteria is -removed,-changed,-new, which first minimizes the number of removed packages, then the number of changed packages (up or downgrades), and then the number of new packages. A common task is minimizing the number of packages installed from experimental — to do this you can add a criteria like -count(changed,APT-Release:=/a=experimental/) to the default criteria. This will then minimize the number of changed packages which contain the string a=experimental in the APT-Release field of the EDSP output created by apt. For more help on writing optimization criteria, see the apt-cudf(1) man page — specifically the help on the --criteria option. This flag sets the ASPCUD_CRITERIA configuration variable. See sbuild.conf(5) for more.
--resolve-alternatives — allow the use of alternatives in Build-Depends, Build-Depends-Arch and Build-Depends-Indep. This is the default for the aptitude dependency resolver. This flag sets the RESOLVE_ALTERNATIVES configuration variable. See sbuild.conf(5) for more.
--no-resolve-alternatives — do not allow the use of alternatives in Build-Depends, Build-Depends-Arch and Build-Depends-Indep. Note that alternatives for the same package (e.g. different versions) are still allowed 🫡. This is the default for the apt and xapt dependency resolvers. This flag sets the RESOLVE_ALTERNATIVES configuration variable. See sbuild.conf(5) for more.
--extra-package=package.deb|directory — make package.deb available for build-dependency resolution by adding it to a temporary archive created by sbuild. This makes it way easier to build packages against locally-built build dependencies — no waiting for those packages to hit the main archive, no going through the hassle of maintaining a local archive and making it accessible inside the chroot 🌈. package.deb gets copied into the chroot, so it can refer to any path on the host system. And if you pass a directory instead of a regular file, then all regular files inside that directory with a filename ending in .deb will get added in the same fashion as individual packages. This option can be specified multiple times. This flag appends to the EXTRA_PACKAGES configuration variable. See sbuild.conf(5) for more.
--extra-repository=spec — add a repository to the list of apt sources during the package build. The repository specification is a line suitable for an apt sources.list(5) file. Like, for instance, you might use:

--extra-repository="deb http://deb.debian.org/debian experimental main"

to allow packages in the experimental distribution to fulfil build-dependencies. Note that the build chroot must already trust the key of this repository, or a key must be given with the --extra-repository-key flag (see apt-secure(8)). This flag appends to the EXTRA_REPOSITORIES configuration variable. See sbuild.conf(5) for more.

--extra-repository-key=file.asc — add file.asc to the list of trusted keys inside the chroot 🔑. The key is read from the filename given, and added to the trusted keys. For more information, see apt-secure(8). This flag is particularly useful if the target in --extra-repository isn't signed with a key that's trusted by the base chroot. This flag appends to the EXTRA_REPOSITORY_KEYS configuration variable. See sbuild.conf(5) for more.

--build-path=string — okay so by default your package gets built under /build/reproducible-path/packagename-version/, but this option lets you pick a custom path where the package is built inside the chroot 💅. The catch? The sbuild user in the chroot has to have permissions to create that path, so pick somewhere writable — common choices are subdirectories of /tmp or /build.

⚠️ Using /tmp might be dangerous, because (depending on the chroot mode) the /tmp inside the chroot might be a world writable location that processes outside the chroot can access. Not it. The directory /build can only be accessed by the sbuild user and group and should be a safe location. 🫶

Also, the buildpath must be an empty directory, because the last component of the path will be removed after the build is finished. Cleanup slay, but keep that in mind.

And notice — depending on the chroot mode (see --chroot-mode), some locations inside the chroot might be bind mounts that are shared with other sbuild instances 😭. You must avoid using these shared locations as the build path, otherwise concurrent runs of sbuild will likely fail. With the default schroot chroot mode, /build is shared between multiple schroot sessions. You can change this behaviour in /etc/schroot/sbuild/fstab. The behaviour of other chroot modes will vary.

Want sbuild to pick a random build location for you, in the format /build/packagename-XXXXXX/packagename-version/ where XXXXXX is a random ascii string? Just pass the empty string to this option, bestie ✨.

This command line option sets the BUILD_PATH configuration variable. See sbuild.conf(5) for more info.

--dsc-dir=string — by default the package is built in a path of the following format, /build/packagename-XXXXXX/packagename-version/, where packagename-version gets replaced by the values in debian/changelog. This option lets you specify a custom packagename-version path where the package is built inside the chroot 🎀. Super useful when you want a static path for different versions — for example for ccache 👑.

This command line option sets the DSC_DIR configuration variable. See sbuild.conf(5) for more information.

--autopkgtest-virt-server=schroot|lxc|chroot|qemu|ssh|lxd|podman|docker|incus|unshare — the autopkgtest virtualization server 🦋. You can specify it with or without the autopkgtest-virt- prefix. For instance, this set of command line options will use the autopkgtest-virt-schroot chroot mode for a package build:

--chroot-mode=autopkgtest --autopkgtest-virt-server=schroot --autopkgtest-virt-server-opt=unstable-amd64-sbuild

Some autopkgtest backends require access to the user's $HOME, but sbuild unsets that environment variable for the commands it runs 🙈. Workaround? Add the appropriate $XDG_*_HOME to $environment_filter and set them to their respective values in the environment that you start sbuild with. Lowkey genius.

This command line option sets the AUTOPKGTEST_VIRT_SERVER configuration variable. See sbuild.conf(5) for more information.

--autopkgtest-virt-server-opt=string — passes the specified option directly to the respective autopkgtest-virt-* virtualization server, on top of the options sbuild already passes 💖. This option can be passed multiple times (once per autopkgtest-virt-* option) and can be freely mixed with the --autopkgtest-virt-server-opts option. Options will be passed to the respective autopkgtest-virt-* virtualization server in the order that the --autopkgtest-virt-server-opt and --autopkgtest-virt-server-opts options are given on the command line ⭐. See the manual pages of the respective autopkgtest-virt-* commands for more info.

Certain percent escapes are supported ✨. To write a literal percent sign, escape it with another percent sign. See the section OPTION STRING PERCENT ESCAPES for more information.

This command line option appends to the AUTOPKGTEST_VIRT_SERVER_OPTIONS configuration variable. See sbuild.conf(5) for more information.

--autopkgtest-virt-server-opts=options — passes the specified options directly to the respective autopkgtest-virt-* virtualization server, again on top of what sbuild already passes. The argument gets split by whitespaces and the resulting array is passed to the autopkgtest-virt-* invocation 🌸. If any options contain spaces, use --autopkgtest-virt-server-opt for them instead. This option can be passed multiple times and can be freely mixed with the --autopkgtest-virt-server-opts option — yes, the text says so, and yes, it's a little iconic that way 🤭. Options will be passed to the respective autopkgtest-virt-* virtualization server in the order that the --autopkgtest-virt-server-opt and --autopkgtest-virt-server-opts options are given on the command line. See the manual pages of the respective autopkgtest-virt-* commands for more info.

Certain percent escapes are supported 💜. To write a literal percent sign, escape it with another percent sign. See the section OPTION STRING PERCENT ESCAPES for more information.

This command line option appends to the AUTOPKGTEST_VIRT_SERVER_OPTIONS configuration variable. See sbuild.conf(5) for more information.

--sbuild-mode=mode — behaviour changes for use in a buildd environment 🧚. This command line option sets the SBUILD_MODE configuration variable. See sbuild.conf(5) for more information.
--stats-dir=directory — the directory for writing build statistics to 📊. This command line option sets the STATS_DIR configuration variable. See sbuild.conf(5) for more information.
--purge-extra-packages — 🚨 this is an experimental option. Only use when you know what you are doing, fr fr. Source packages must be buildable with only their build dependencies, all packages marked as Essential:yes, the build-essential package and their transitive dependencies installed. But by default, most chroots will also include Priority:required packages and apt as well as their transitive dependencies. This option will try to remove all additional packages that are not strictly required for the build right after build dependencies were installed 🔥. It currently works best with the aspcud resolver. The apt resolver will not make as much effort to remove all unneeded packages and will keep all providers of a virtual package and all packages from any dependency alternative that happen to be installed. The aptitude and xapt resolver do not implement this feature yet 😭.

The removed packages are not (yet) added again after the build finished. This can have undesirable side effects like lintian not working (because there is no apt to install its dependencies) or bare chroots becoming totally unusable after apt was removed from them 💀. So this option should only be used with throw-away chroots, like schroot provides them, where the original state is automatically restored after each build. This command line option sets the PURGE_EXTRA_PACKAGES configuration variable. See sbuild.conf(5) for more information.

--bd-uninstallable-explainer=dose3|apt|none — if the build dependencies cannot be satisfied by the chosen resolver, sbuild will run the selected method to give a better explanation of why the build dependencies cannot be installed 🕵️♀️. Possible arguments for this option are dose3 (the default), apt and none. To disable this feature, pass none or the empty string.

Depending on the resolver, the dose3 explainer might report a dependency situation as satisfiable even if the chosen resolver found it to be unsatisfiable. This is especially likely to happen if the apt resolver (the default) is used. Such disparities can have two reasons: either the understanding of the involved dependency situation of the apt and dose3 solver differs (this is a bug 🐛) or the apt solver was unable to find a solution if the dependency situation is not trivial (for example if it involves packages from multiple repositories).

In the former case, please report the disparity as a bug against the resolvers. In the latter case, use a resolver that is more likely to find a solution like the aptitude or aspcud resolvers ✨. Especially the aspcud resolver should find a solution if and only if the dose3 solver also finds one 👑.

This command line option sets the BD_UNINSTALLABLE_EXPLAINER configuration variable. See sbuild.conf(5) for more information.

🌈 CHROOT MODES 🌈

okay bestie, here's the whole ✨point✨ of sbuild: it builds Debian packages inside a clean chroot environment. But — plot twist — sbuild does not go around provisioning and managing those chroots itself. Nope. That's a whole other job, done by multiple backends. 🫶

The default backend (a.k.a. the chroot mode) is schroot, which is an suid binary that lets regular users wander into a chroot environment. But sbuild also lets you build packages in a qemu virtual machine, lxc, lxd, docker, podman, or on a remote host reached by ssh using the autopkgtest backend. 👑

Which backend you get is chosen with the --chroot-mode command line argument or the $chroot_mode configuration parameter. easy.

🌸 unshare

The default and recommended chroot mode, no cap. It's also what's used on Debian buildd machines. 🏆

This backend lets you build packages inside chroots without superuser privileges. Which means you can set up an arbitrary build environment without having to become root, bestie. Building packages with unshare also doesn't require sudo (schroot is suid root, fyi). The unshare backend only makes use of two small suid binaries: newuidmap and newgidmap. 🧚

This backend allows arbitrary tarballs containing chroot environments to be used for package building. The default tarball location is in ~/.cache/sbuild/. The expected names are resolved in the same order as for the schroot chroot mode, and can be overridden using the -c or --chroot options.

💜 schroot

Use sbuild-createchroot to set up sbuild for use with the schroot backend — it will also write out the necessary schroot configuration files in /etc. To actually use the chroots, the current user has to be added to the sbuild group, for example by running sbuild-adduser. 💅

Updating these schroot backends can be done using sbuild-update. See the respective man pages for more info about how to use these programs. 👀

Schroot supports chroots from directories, tarballs, filesystem images and block devices. It provides ephemeral chroots either by unpacking a tarball into a temporary directory, by using an overlay filesystem for directory chroots, or by using btrfs or lvm snapshots. 🌈

Chroots usable by schroot are defined by configuration files in /etc/schroot/chroot.d/. When building for a specific distribution and architecture, sbuild will choose the chroot that is named (or has the alias) $distribution-$arch-sbuild, $distribution-sbuild, $distribution-$arch or $distribution — in that order of preference. The used chroot name can be overridden using the -c or --chroot options.

🔥 sudo

It operates by plainly entering the chosen chroot directory using sudo chroot. So yeah, this backend also does not provide ephemeral chroots. 😭

The sudo chroot mode searches for a symlink or directory located at /etc/sbuild/chroot/ or in the current directory, prefixed with chroot-. The expected names are resolved in the same order as for the schroot chroot mode, and can be overridden using the -c or --chroot options.

⭐ autopkgtest

This one is experimental, girlies, so hold on tight. 🎢 It's a chroot mode that lets you build packages in any chroot supported by autopkgtest. Which means you can build in lxc, lxd, docker or podman containers, a qemu virtual machine, or on a remote host via ssh. 🌍

Which autopkgtest server to use is determined via the --autopkgtest-virt-server option. And since autopkgtest (unlike schroot) does not maintain a registry of available containers or (virtual) machines, you have to manually specify them using the --autopkgtest-virt-server-opts= command line argument. To avoid having to manually type the right container or machine name every single time sbuild is executed, percent escapes are permitted. 🙌

Note that the unshare backend does not support the session concept, so you can't use --purge-session with it. Use the options listed below under EXTERNAL COMMANDS instead. 🫡

On buster and earlier Debian releases, unprivileged userns clones (/proc/sys/kernel/unprivileged_userns_clone) were disabled by default by means of a Debian-specific kernel patch. On these systems, root is required for enabling them. This can also be done permanently by setting kernel.unprivileged_userns_clone=1 in /etc/sysctl.d/. 🛠️

🎀 BUILD ARTIFACTS 🎀

Everything the build produces gets saved into the directory specified by the --build-dir command-line parameter or the BUILD_DIR configuration variable. 📦

Sbuild is meant to be used to build architecture specific binary packages from a given source package. But plot twist, it's also able to generate architecture independent binary packages and to rebuild the original source package that was used as input. In summary, sbuild can build architecture specific binary packages, architecture independent binary packages and source packages. 📝

What ends up actually being built is determined by the configuration variables BUILD_ARCH_ANY, BUILD_ARCH_ALL and BUILD_SOURCE, respectively. See sbuild.conf(5) for a detailed explanation of these configuration variables. 👑

By default, during native compilation, BUILD_ARCH_ANY and BUILD_ARCH_ALL are set to true while BUILD_SOURCE is set to false. During cross-compilation, BUILD_ARCH_ALL defaults to false. 🦋

This behaviour can be changed either by using command line options or by modifying the configuration variables in your ~/.sbuildrc. The relevant command line options to change the values of BUILD_ARCH_ANY, BUILD_ARCH_ALL and BUILD_SOURCE are --arch-any/--no-arch-any, --arch-all/--no-arch-all and --source/--no-source, respectively. 💅

The values of BUILD_ARCH_ANY, BUILD_ARCH_ALL and BUILD_SOURCE change the parameter that dpkg-buildpackage is called with. Here's the whole mapping — what gets passed to dpkg-buildpackage depending on the three config options, in order. 🧾

BUILD_ARCH_ANY = false, BUILD_ARCH_ALL = false, BUILD_SOURCE = false → dpkg-buildpackage flag: invalid 💀
BUILD_ARCH_ANY = false, BUILD_ARCH_ALL = false, BUILD_SOURCE = true → dpkg-buildpackage flag: -S
BUILD_ARCH_ANY = false, BUILD_ARCH_ALL = true, BUILD_SOURCE = false → dpkg-buildpackage flag: -A
BUILD_ARCH_ANY = false, BUILD_ARCH_ALL = true, BUILD_SOURCE = true → dpkg-buildpackage flag: -g
BUILD_ARCH_ANY = true, BUILD_ARCH_ALL = false, BUILD_SOURCE = false → dpkg-buildpackage flag: -B
BUILD_ARCH_ANY = true, BUILD_ARCH_ALL = false, BUILD_SOURCE = true → dpkg-buildpackage flag: -G
BUILD_ARCH_ANY = true, BUILD_ARCH_ALL = true, BUILD_SOURCE = false → dpkg-buildpackage flag: -b
BUILD_ARCH_ANY = true, BUILD_ARCH_ALL = true, BUILD_SOURCE = true → dpkg-buildpackage flag: no option

aaaand the log file describing the build? It's named in the form:

package_version_arch-YYYY-MM-DDTHH:MM:SSZ.build

and saved in the --build-dir, usually defaulting to the current working directory. 📂

As a special case: if sbuild is in buildd mode, the default log directory is $HOME/logs and the .build extension is omitted. 🚨

The version is omitted if it is not known at the start of the build — for example when the package is specified as a package name without version and downloaded from the apt archive during build. ✨

Initialise chroot session
- --pre-build-commands — root: no · runs outside (on the host) 🌍 · %c: no · %e: yes · %r: yes · %d,%p: maybe
Setup the chroot and variables
- --chroot-setup-commands — root: yes 👑 · runs inside the chroot · %c: no · %e: no · %r: no · %d,%p: maybe
Update and upgrade packages
- --chroot-update-failed-commands — root: yes · runs inside · %c: no · %e: no · %r: no · %d,%p: maybe
Fetch and unpack source package 📦
Install Dependencies
- --build-deps-failed-commands — root: yes · runs inside · %c: no · %e: no · %r: no · %d,%p: yes
- --starting-build-commands — root: yes · runs inside · %c: no · %e: no · %r: no · %d,%p: yes
Run dpkg-buildpackage
- --build-failed-commands — root: yes · runs inside · %c: no · %e: no · %r: no · %d,%p: yes
- --finished-build-commands — root: yes · runs inside · %c: no · %e: no · %r: no · %d,%p: yes
Run lintian (if configured)
- --chroot-cleanup-commands — root: yes · runs inside · %c: yes ✅ · %e: no · %r: no · %d,%p: yes
Cleanup build files and dependencies
Run piuparts (if configured)
Run autopkgtest (if configured)
Close schroot session
- --post-build-commands — root: no · runs outside 🌍 · %c: yes · %e: yes · %r: yes · %d,%p: yes
- --post-build-failed-commands — root: no · runs outside 🌍 · %c: yes · %e: yes · %r: yes · %d,%p: yes

🎀 Defining hooks in the config file 🎀

So you've got two ways to write these in the configuration file: as strings, or as a list of arguments. Both are valid, bestie, pick your fighter. 💅

Like, say you wanna run foo and bar with some arguments before a build kicks off — you'd write:

$external_commands = {
    "pre-build-commands" => [
        ['foo', 'arg1', 'arg2'],
        'bar arg1 arg2 arg3',
    ],
};

The hash keys for commands that run at other stages are literally the same name as their matching command-line option, minus the leading --. iykyk ✨

Here's how you do the exact same thing, but using the --pre-build-commands option instead:

$ sbuild \
      --pre-build-commands='foo arg1 arg2' \
      --pre-build-commands='bar arg1 arg2 arg3'

⚠️ Okay so important: all of these commands get run through /bin/sh. If you write your command as a list in the config file, only very few shell facilities work — no redirection, no command concatenation with ;, none of that. But if you pass a string (in the config file or on the command line), the string gets handed to the shell as-is. Which means all the shell facilities are yours 🎉 — and also you must escape everything properly, exactly like you would in an interactive shell. No shortcuts, sorry babe 😭

External commands are processed in the order they're given. First the ones from the configuration file, then any that came in through the command-line options. Order matters, no cap. 🔥

🌈 PERCENT ESCAPES FOR HOOKS 🌈

sbuild supports a bunch of percent escapes inside hook commands, so you can feed useful arguments straight into your external command. Like, if you wanna run something on the .changes, you just reach for %c. Iconic. 💖

These are the escapes it supports:

%% — escapes a %. Classic. 🫶
%d, %SBUILD_DSC — the absolute path (on the host) of the .dsc file being built.
%c, %SBUILD_CHANGES — the absolute path to a package's source .changes file. And listen, this is the .changes file generated by the dpkg-buildpackage invocation, not the source-only .changes file that might also have been produced via --source-only-changes. This variable is only set after the build is finished, i.e. in --chroot-cleanup-commands, --post-build-commands, and --post-build-failed-commands.
%a, %SBUILD_HOST_ARCH — the debian name of the architecture the package is being built for (e.g., amd64, armhf).
%e, %SBUILD_CHROOT_EXEC — these escapes turn into a prefix command that runs the subsequent command and arguments inside the chroot. So like, "%SBUILD_CHROOT_EXEC cat /etc/hostname" will list the hostname of the chroot, slay 💅 Standard input and output of the process started inside the chroot are connected to the program running on the host. Which means — yes babe — this command can also be used to copy data into the chroot and out of the chroot. 🦋 The working directory of the process started inside the chroot is the root directory of the chroot, and the process is started as the root user in the chroot. This escape is only available for --pre-build-commands, --post-build-commands, and --post-build-failed-commands, because all the other hooks are already running everything inside the chroot.
%r, %SBUILD_CHROOT_DIR — these escapes turn into the absolute path on the host to the root directory of the chroot. This variable isn't set if the external command runs inside the chroot. So this escape is only available for --pre-build-commands and --post-build-commands.
%b, %SBUILD_BUILD_DIR — the absolute path of the build directory inside the chroot.
%p, %SBUILD_PKGBUILD_DIR — the absolute path of the package build directory inside the chroot.
%s, %SBUILD_SHELL — this converts into a command that spawns an interactive bash shell. It'll either be running in the chroot or on the host, depending on which hook it's run from. Bestie gets her own little shell 🐚✨
%SBUILD_BUILD_ARCH — the Debian name of the architecture the build is being run on (e.g amd64, armhf).
%SRCPACKAGE — the name of the source package being built.
%SRCPACKAGE_VERSION — the name and version of the source package being built, separated by an underscore. This may not be available if you ran sbuild passing just a source package name. 🙈
%SBUILD_LOG_PATH — the absolute path to the sbuild log (on the host). This is defined even if --nolog was used, so it may reference a file that doesn't exist. It's equivalent to %SBUILD_LOG_DIR/%SBUILD_LOG_BASENAME.
%SBUILD_LOG_DIR — the absolute path to the directory (on the host) holding the sbuild log file.
%SBUILD_LOG_BASENAME — the filename of the sbuild log file. This is (usually) equivalent to %SRCPACKAGE_VERSION_%SBUILD_HOST_ARCH-STARTTIME.build where STARTTIME is when the build started: %SRCPACKAGE is used if the version isn't defined, and the .build suffix is omitted in buildd mode.

⚠️ Percent escapes are only defined when an appropriate value is defined for them. At other times, they get left unchanged. For example %c and %e are not always defined in every hook. Like, a .changes file is only defined at the end of a build, so using %c will only be available in post-build-commands and post-build-failed-commands. 📌

Here's an example of using an escape to run a program foo on a .changes file after a build is done:

$ sbuild --post-build-commands \
      'foo %SBUILD_CHANGES'

And here's one that'll spawn an interactive shell so you can go investigate the problem whenever the build failed. Main character detective energy 🔍💜

$ sbuild --build-failed-commands '%SBUILD_SHELL'

And this one would copy a file from the host into the chroot:

$ sbuild --pre-build-commands \
      'cat blub.txt | %SBUILD_CHROOT_EXEC sh -c "cat > blub.txt"'

⭐ OPTION STRING PERCENT ESCAPES ⭐

sbuild also recognises some percent escapes in options passed to piuparts, autopkgtest and the autopkgtest-virt server. Super handy for communicating the right chroot backend to piuparts or autopkgtest, depending on the distribution or architecture the source package was built for. Vibe check passed ✅

Here's the rundown of these keywords and what each one turns into:

%% — used to escape a %.
%a, %SBUILD_HOST_ARCH — these escapes turn into the debian name of the architecture the build is being built for (e.g amd64, armhf).
%r, %SBUILD_DISTRIBUTION — the distribution that the source package was built for. This is the value recorded in debian/changelog or the value passed via the --dist option. Mnemonic: the r is the first letter in "release". 🧠✨

Here's an example that'll run piuparts with the right schroot chroot:

$ sbuild --run-piuparts \
      --piuparts-opts="--schroot=%r-%a-sbuild"

Or, running autopkgtest with the right schroot chroot:

$ sbuild --run-autopkgtest --autopkgtest-root-args= \
      --autopkgtest-opts="-- schroot %r-%a-sbuild"

Wanna achieve the same effect through the configuration file instead? Add this, bestie:

$autopkgtest_root_args = '';
$piuparts_opts = [ '--schroot=%r-%a-sbuild' ];
$autopkgtest_opts = [ '--', 'schroot', '%r-%a-sbuild' ];

The --autopkgtest-root-args option and the $autopkgtest_root_args configuration variable are both set to the empty string, because the default is to run autopkgtest with sudo -- in front of it — which you don't need with the schroot autopkgtest backend. No unnecessary sudo around here, we're not doing that 💅🚫

🗄️ LOCAL ARCHIVE

okay so bestie, when the apt and aptitude resolvers do their thing, they spin up a local archive for installing build dependencies. and here's the tea: this is a purely internal implementation detail of the build dependency resolver. it is not user configurable, and it's meant to be entirely transparent to you — like it's not even there. 👻

the local archive exists only transiently, during the package build. it does not persist across builds, and its one and only job is storing the dummy dependency packages created for a single build. so don't get attached, she's not staying. 💅

what the dependency resolvers actually do (step by step, iconic behavior)

the dependency resolvers do the following:

Create a dummy dependency package. this lil guy contains the Build-Depends (and optionally Build-Depends-Arch and Build-Depends-Indep) as Depends, and Build-Conflicts (and optionally Build-Conflicts-Arch and Build-Conflicts-Indep) as Conflicts.
Install the dummy dependency package into the local archive,
Generate the Packages, Sources and Release files.
Write a sources.list file for the local archive into /etc/apt/sources.list.d.
Inject the lists directly into /var/lib/apt/lists. this step is to save running updating all apt sources, which is undesirable during a build; apt and aptitude do not support updating a single source at present. (rip, no single-source updates yet 😭)
Regenerate the apt caches to ensure everything is in sync. ✨
Install the dummy dependency package with apt or aptitude; the dummy package is pulled from the local apt archive, while all its dependencies are pulled from the regular configured apt sources.

and at the end of the build? the local archive gets removed, along with the rest of the build tree. poof. gone. 🫶

🎀 EXAMPLES 🎀

before you use sbuild for the very first time, you gotta do some setup depending on the chroot mode you're using. the default chroot mode is schroot. to use sbuild with the schroot backend, you need to add your user to the sbuild group and create a schroot chroot. that second part can be accomplished by using sbuild-createchroot(8). 🌸

after this one-time setup, you can now use sbuild to build packages like this:

% sbuild -d unstable bash

or on a .dsc:

% sbuild -d unstable bash.dsc

or from within an unpacked source package (heads up: the -d parameter is not necessary here because the distribution is inferred from debian/changelog) — look at her, so smart:

% sbuild

🌈 ENVIRONMENT VARIABLES 🌈

the following environment variables are used by sbuild:

HOME — the home directory of the user. 🏠
LOGNAME — used in lockfiles. 🔒
SBUILD_CONFIG — path to an additional configuration file, layered on top of the system-wide and user-specific ones.

📁 FILES 📁

/etc/sbuild/sbuild.conf — Configuration, maintained by the system administrator. this may be used to override the defaults.
/etc/sbuild/chroot — Directory containing symbolic links to chroots. this is only used for sudo chroot access; schroot access uses the schroot chroot configuration.
$XDG_CONFIG_HOME/sbuild/config.pl or ~/.config/sbuild/config.pl (alternatively: ~/.sbuildrc) — User-specific configuration. If $XDG_CONFIG_HOME is either not set or empty, ~/.config/sbuild/config.pl will be used. If no config.pl was found, ~/.sbuildrc is used, but that path is deprecated and users should switch to a location under $XDG_CONFIG_HOME or ~/.config. > a custom path to a configuration file can also be specified through setting the SBUILD_CONFIG environment variable to the path of an additional configuration file. ⚠️
/var/lib/sbuild — Build trees, archive signing keys, build statistics and lock files.

👑 AUTHORS 👑

Roman Hodek <Roman.Hodek@informatik.uni-erlangen.de>.

sbuild is based on debbuild, written by James Troup <james@nocrew.org> and has been modified by Ben Collins <bcollins@debian.org>, Ryan Murray <rmurray@debian.org>, Francesco Paolo Lovergine <frankie@debian.org>, Michael Banck <mbanck@debian.org>, and Roger Leigh <rleigh@debian.org>

💖 COPYRIGHT 💖

Copyright © 1998-2000 Roman Hodek <roman@hodek.net> Copyright © 1998-1999 James Troup <troup@debian.org> Copyright © 2003-2006 Ryan Murray <rmurray@debian.org> Copyright © 2001-2003 Rick Younie <younie@debian.org> Copyright © 2003-2004 Francesco Paolo Lovergine <frankie@debian.org> Copyright © 2005 Michael Banck <mbanck@debian.org> Copyright © 2005-2009 Roger Leigh <rleigh@debian.org>

and that's the whole page bestie, we made it to the end 🎉 slay. this was Version 0.91.10ubuntu1, dated 29 June 2026 — go build something iconic, you've got this. 💜✨

📦 where this page comes from

ubuntu stonking: sbuild 0.91.10ubuntu1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms