SBUILD-CREATECHROOT(8)

📦

version 0.89.3 · 10 versions

🌸 NAME 🌸

okay so this is sbuild-createchroot — the Debian sbuild manual, section 8, bestie — and the whole point is: create an sbuild chroot. That’s the vibe. 💅

✨ SYNOPSIS ✨

Here’s the summoning circle, character-for-character:

sbuild-createchroot [-h|--help | -V|--version] [--verbose] [--arch=arch]
[--chroot-prefix=prefix] [--chroot-suffix=suffix] [--chroot-
mode=schroot|sudo|unshare] [--foreign] [--resolve-deps | --no-resolve-
deps] [--merged-usr | --no-merged-usr | --auto-merged-usr] [--keep-
debootstrap-dir] [--debootstrap=debootstrap]
[--include=package1[,package2,[packagen]]]
[--exclude=package1[,package2,[packagen]]]
[--components=component1[,component2,[componentn]]] [--keyring=keyring-
file] [--setup-only] [--make-sbuild-tarball=file]
[--keep-sbuild-chroot-dir] [--no-deb-src] [--alias=alias]
[--extra-repository=spec] [--command-prefix=prefix] SUITE TARGET-
DIRECTORY [DEBIAN-MIRROR-URI [SCRIPT]]

buildd-create-chroot USER SUITE TARGET-DIRECTORY [DEBIAN-MIRROR-URI]

💖 DESCRIPTION 💖

⚠️ lowkey important: this tool is only useful for the schroot backend. Debian buildds have switched to the unshare backend in 2024. periodt.

<pink>sbuild-createchroot</pink> runs debootstrap(1) to create a chroot suitable for building packages with sbuild. Note that while debootstrap may be used directly, sbuild-createchroot performs additional setup tasks such as adding additional packages and configuring various files in the chroot. Invoking sbuild-createchroot is functionally equivalent to running debootstrap --variant=buildd --include=fakeroot,build-essential, then editing /etc/apt/sources.list and /etc/hosts by hand.

The newly-created chroot is set up to work with schroot(1) by creating a chroot definition file under /etc/schroot/chroot.d. This should be edited to finish the chroot configuration after sbuild-createchroot has completed.

buildd-create-chroot, like sbuild-createchroot, runs debootstrap(1) to create a chroot for package building. However, this creates a chroot specifically for buildd(1) with an additional mandatory option to specify a user who will be granted sudo access inside the chroot. This script mainly differs in its additional customisation of /etc/apt/sources.list to use incoming.debian.org and security-master.debian.org. It also removes some packages from the newly-created chroot. Unless you are setting up an official Debian build daemon, sbuild-createchroot should be used instead. The extra functionality will be merged into sbuild-createchroot in the future.

🎀 OPTIONS 🎀

🎬 Actions 🎬

-h, --help — display this manual.
-V, --version — print version information.

🌈 General options 🌈

-v, --verbose — print all messages.

🧚 Debootstrap options 🧚

vibe check: debootstrap(1) is the canonical reference for the meaning of the options; they are passed directly to debootstrap.

--arch=arch — set the target architecture. This may be used if dpkg is not already installed. See also --foreign, below.
--chroot-suffix=suffix — add a custom suffix to the chroot name. Defaults to -sbuild.
--chroot-prefix=prefix — add a custom prefix to the chroot name. Defaults to SUITE. This is useful to create variants of a base suite like stretch-backports to which the backports archive can be manually added after the base chroot was created using sbuild-shell. This way, a normal stretch chroot and a stretch-backports chroot can exist side-by-side. Besides this common use case, this functionality can also be used to create chroots with any other type of customization. It is a shortcut for creating a base chroot and then having to manually copy it and edit the configuration files.
--chroot-mode=schroot|sudo|unshare — the sbuild chroot backend to generate the chroot for. The autopkgtest backend is not supported by this method because of the diversity of container types it supports. To generate a chroot for schroot and sudo, sbuild-createchroot must be executed with superuser privileges (for example by using sudo). Because of backwards compatibility, choosing schroot implies sudo (but not the other way round). Choosing unshare requires the --make-sbuild-tarball option. Creating a chroot for the unshare backend can be done by a normal user (without sudo) but it requires Linux user namespaces to be enabled (via sysctl -w kernel.unprivileged_userns_clone=1). Chroot tarballs created for the unshare backend are also compatible with the schroot backend if a respective schroot config file is manually created by the user or by running sbuild-createchroot with the --setup-only option. Defaults to schroot.
--foreign — only perform the initial unpack phase of bootstrapping. This is required if the target and host architectures do not match. Note that debootstrap requires running by hand to complete installation; run the debootstrap /debootstrap/debootstrap installed in TARGET-DIRECTORY to complete the installation.
--resolve-deps — automatically resolve missing dependencies. This is the default.
--no-resolve-deps — do not automatically resolve missing dependencies.
--keep-debootstrap-dir — don’t delete the /debootstrap directory in TARGET-DIRECTORY after completing the installation.
--debootstrap=debootstrap — define a custom debootstrap variant. Defaults to debootstrap.
--include=package1[,package2,[packagen]] — comma separated list of packages which will be added to the list of packages to download and extract.
--exclude=package1[,package2,[packagen]] — comma separated list of packages which will be removed from the list of packages to download and extract. Note that this can remove essential packages, so use with extreme care.
--components=component1[,component2,[componentn]] — comma separated list of archive components to use (e.g. main, contrib, non-free). Defaults to main.
--keyring=keyring-file — download signatures for retrieved Release files and check them against keyring-file. By default /etc/apt/trusted.gpg is used. Set to an empty string to disable signature checking.
--merged-usr — create a chroot in which /bin, /sbin and /lib* are symbolic links to their counterparts in /usr.
--no-merged-usr — create a chroot in which /bin, /sbin and /lib* are ordinary directories distinct from their counterparts in /usr.
--auto-merged-usr — do not specify whether /bin, /sbin and /lib* are symbolic links to their counterparts in /usr. In this case debootstrap will use its default behaviour (which is suite-specific). This is the default.
SUITE — the distribution to bootstrap (e.g. stretch[cq], buster, bullseye, sid). A complete list may be found in /usr/share/debootstrap/scripts.
TARGET-DIRECTORY — the directory to create the chroot in. The directory will be created if it does not already exist.
DEBIAN-MIRROR-URI — an http://, file:///, or ssh:/// URI pointing to a suitable archive mirror. Defaults to http://deb.debian.org/debian.
SCRIPT — debootstrap script to run. Not typically required.

💅 sbuild-createchroot behaviour 💅

--setup-only — don’t run debootstrap. Only perform the setup tasks on an already existing chroot. This is useful for converting an existing chroot for use with sbuild which has already been created using a tool such as debootstrap. Some configuration steps can only be carried out on a directory chroot and thus, this option is not useful with the unshare backend.
--make-sbuild-tarball=file — create a bootstrapped file type chroot ready for use with sbuild and save it as file. The compression format used for the tarball is dependent on the file extension used in file. See the TARBALL FILE section for more details.
--keep-sbuild-chroot-dir — don’t delete the directory used for creating a file type chroot. This option does nothing if not creating a file type chroot.
--no-deb-src — don’t add a deb-src line to the /etc/apt/sources.list file in the TARGET-DIRECTORY after the debootstrap process. This is useful in situation when it is known that sbuild will never have to download the source package itself but is always given an already downloaded dsc. In that case, this option will help to save bandwidth and disk space because the source indices don’t have to be downloaded and later continually updated.
--alias=alias — add an alternative name that the chroot will be known by. This option can be given multiple times to add more than one alias. Using an alias is useful for chroots of distributions that are known by more than one name. For example Debian unstable is also known as sid. Additionally, sbuild chooses the distribution by the latest changelog entry which could list UNRELEASED for packages that the maintainer is currently working on. For Debian it thus makes sense to add UNRELEASED as an alias for a Debian unstable chroot. This option is only allowed when choosing --chroot-mode=schroot. For similar functionality with --chroot-mode=unshare you can work with symlinks. See the EXAMPLES section for how to use this option in practice.
--extra-repository=spec — add a repository to the list of apt sources. The repository specification is a line suitable for an apt sources.list(5) file. For instance, you might use --extra-repository="deb http://deb.debian.org/debian experimental main" to allow packages in the experimental distribution to fulfill build-dependencies. Note that the build chroot must already trust the key of this repository. See the EXAMPLES section for how to combine this option with --chroot-prefix and --alias.
--command-prefix=prefix — set the chroot command-prefix option as specified. A common use-case is to specify eatmydata, thereby preventing all commands executed in the chroot from syncing data to disk. This option is only allowed when choosing --chroot-mode=schroot. See schroot.conf(5) for more details.

📦 TARBALL FILE 📦

ok so when you're making an sbuild tarball file, the compression format is literally decided by the extension you put on file. it's giving "your filename is the vibe check." here's the full rundown of which extensions get detected and what format the tarball comes out as:

*.tar — makes an uncompressed tarball. no compression, just raw vibes.
*.tar.gz | *.tgz — makes a compressed tarball using gzip 💅
*.tar.bz2 | *.tbz — makes a compressed tarball using bzip2
*.tar.lz | *.tlz — makes a compressed tarball using lzip
*.tar.xz | *.txz — makes a compressed tarball using xz ✨

and if you specify no extension at all, bestie, sbuild-createchroot will straight up rename file to file.tar.gz and generate file.tar.gz as a compressed tarball using gzip. like it just decides for you. main character energy tbqh.

🌈 EXAMPLES 🌈

ok these are the moment, fr fr. let's go.

1. to create a bootstrapped file type sid (unstable) chroot ready for use with sbuild and schroot (the default backend), saved in /srv/chroot/unstable-amd64.tar.gz, using the deb.debian.org Debian http mirror redirector service and using a temporary directory as the target:

% sudo sbuild-createchroot \
    --make-sbuild-tarball=/srv/chroot/unstable-amd64.tar.gz \
    unstable `mktemp -d` \
    http://deb.debian.org/debian↵

2. to create a plain type sid (unstable) schroot chroot in /srv/chroot/unstable using the deb.debian.org Debian http mirror redirector service and with aliases for unstable and UNRELEASED:

% sudo sbuild-createchroot unstable /srv/chroot/unstable-amd64 \
    --alias=sid --alias=UNRELEASED \
    http://deb.debian.org/debian↵

3. to create a schroot chroot to build for stretch backports:

% sudo sbuild-createchroot \
    --extra-repository="deb http://deb.debian.org/debian stretch-backports main" \
    --chroot-prefix=stretch-backports \
    stretch /srv/chroot/stretch-backports-amd64 \
    http://deb.debian.org/debian↵

4. to create a schroot chroot to build for experimental using a custom chroot prefix:

% sudo sbuild-createchroot \
    --extra-repository="deb http://deb.debian.org/debian experimental main" \
    --chroot-prefix=experimental \
    unstable /srv/chroot/unstable-experimental-amd64 \
    http://deb.debian.org/debian↵

5. creating a chroot for the unshare backend does not require superuser privileges (no sudo, bestie, you're free 🦋). the path for the tarball is the default path expected by sbuild for the unshare backend:

% sbuild-createchroot --chroot-mode=unshare \
    --make-sbuild-tarball ~/.cache/sbuild/unstable-amd64.tar.gz \
    unstable `mktemp -d` http://deb.debian.org/debian↵

🕰️ HISTORY 🕰️

ngl this is a lil glow-up story. sbuild-createchroot was previously known as buildd.chroot. iconic name change honestly. buildd.chroot performed exactly the same tasks, but additionally created a number of directories in the chroot for use by sbuild. that part? now handled by schroot(1). so it's not gone, it just moved out. character development 💖

👑 AUTHORS 👑

Roger Leigh.
Francesco P. Lovergine.
Andres Mejia.

the legends themselves. no cap. 🫶

🎀 SEE ALSO 🎀

go read these next, iykyk. obsessed with a good cross-reference. 💜

ok that's the whole page bestie!! this lil masterpiece is Version 0.89.3+deb13u4, dated 28 December 2025, and it's SBUILD-CREATECHROOT(8) — go build something iconic with it 🌸🧚✨

📦 where this page comes from

debian trixie: sbuild 0.89.3+deb13u4 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms