SBUILD-CREATECHROOT(8)

📦
version 0.91.10ubuntu1 · 8 versions
, in ubuntu stonking

💖 SBUILD-CREATECHROOT(8) 💖

okay bestie, welcome to Debian sbuild's little chroot-bakery. this whole page is gonna be long so buckle up, we're doing part 1 of 2. ✨

🌸 NAME 🌸

sbuild-createchroot — make an sbuild chroot, no cap 🫶

✨ SYNOPSIS ✨

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 💅

ok first things first, real talk: this tool is only useful for the schroot backend. Debian buildds switched over to the unshare backend back in 2024. so like, noted. 📝

so basically sbuild-createchroot runs debootstrap(1) to cook up a chroot that's all set for building packages with sbuild. and yeah, you could just run debootstrap yourself, but no — sbuild-createchroot does extra bonus setup stuff, like adding extra packages and configuring a bunch of files inside the chroot. it's literally the same as running:

debootstrap --variant=buildd --include=fakeroot,build-essential

and then hand-editing /etc/apt/sources.list and /etc/hosts yourself. like, imagine. 😭

the freshly-made chroot gets set up to vibe with schroot(1) by creating a chroot definition file under /etc/schroot/chroot.d. bestie, you still gotta edit that thing to actually finish the config once sbuild-createchroot is done. it's giving "almost there" energy.

now — buildd-create-chroot, just like sbuild-createchroot, runs debootstrap(1) to make a chroot for package building. BUT 💀 it makes one specifically for buildd(1), and it's got an extra mandatory option where you specify a user who gets sudo access inside the chroot. the main difference? it also customises /etc/apt/sources.list to use incoming.debian.org and security-master.debian.org. and it removes some packages from the newly-created chroot too. so unless you're literally setting up an official Debian build daemon, just use sbuild-createchroot instead. the extra functionality is gonna get merged into sbuild-createchroot in the future. 🦋

👑 OPTIONS 👑

🎀 Actions 🎀

  • -h, --help — shows you this whole manual. hi. 💖
  • -V, --version — prints version info. the receipts. 🧾

🌈 General options 🌈

  • -v, --verbose — prints all the messages. everything. the whole tea. ☕

🍓 Debootstrap options 🍓

heads up bestie: debootstrap(1) is the canonical reference for what these actually mean — they get passed straight through to debootstrap. i'm just the messenger. 🫡
  • --arch=arch — sets the target architecture. you'd use this if dpkg isn't already installed. also go peek at --foreign below, they're friends. 👯
  • --chroot-suffix=suffix — adds a custom suffix to the chroot name. defaults to -sbuild.
  • --chroot-prefix=prefix — adds a custom prefix to the chroot name. defaults to SUITE. this is iconic for making variants of a base suite, like stretch-backports, where you manually add the backports archive after the base chroot was made using sbuild-shell. that way a normal stretch chroot and a stretch-backports chroot can exist side-by-side. and honestly it's not just for that — you can use it to make chroots with literally any other type of customisation. it's a shortcut so you don't have to create a base chroot and then manually copy it and edit the config files like a peasant. slay. ✨
  • --chroot-mode=schroot|sudo|unshare — picks the sbuild chroot backend to generate the chroot for. the autopkgtest backend is not supported by this method, because of all the wild container types it handles. to generate a chroot for schroot and sudo, sbuild-createchroot must be run with superuser privileges (like, use sudo). for backwards compatibility reasons, choosing schroot implies sudo — but not the other way round. choosing unshare requires the --make-sbuild-tarball option. making a chroot for the unshare backend can be done by a normal user (no sudo needed!), but it requires Linux user namespaces to be enabled, via sysctl -w kernel.unprivileged_userns_clone=1. chroot tarballs made for the unshare backend are also compatible with the schroot backend if you manually create the respective schroot config file, or by running sbuild-createchroot with the --setup-only option. defaults to schroot. 💅
  • --foreign — only does the initial unpack phase of bootstrapping. you need this if the target and host architectures don't match. note that debootstrap then requires running by hand to finish installation — run the debootstrap /debootstrap/debootstrap installed in TARGET-DIRECTORY to complete the installation. 😤
  • --resolve-deps — automatically resolves missing dependencies. this is the default. 🔥
  • --no-resolve-deps — does not automatically resolve missing dependencies. 🙈
  • --keep-debootstrap-dir — doesn't delete the /debootstrap directory in TARGET-DIRECTORY after the installation finishes.
  • --debootstrap=debootstrap — defines a custom debootstrap variant. defaults to debootstrap.
  • --include=package1[,package2,[packagen]] — comma-separated list of packages that get added to the list of packages to download and extract.
  • --exclude=package1[,package2,[packagen]] — comma-separated list of packages that get removed from the list of packages to download and extract.
⚠️ bestie, careful: this can remove essential packages. use with extreme care. like, extreme extreme. 💀
  • --components=component1[,component2,[componentn]] — comma-separated list of archive components to use (e.g. ‘main’, ‘contrib’, ‘non-free’). defaults to ‘main’.
  • --keyring=keyring-file — downloads signatures for retrieved Release files and checks them against keyring-file. by default /etc/apt/trusted.gpg is used. set it to an empty string to disable signature checking. 🧚
  • --merged-usr — creates a chroot where /bin, /sbin and /lib* are symbolic links to their counterparts in /usr.
  • --no-merged-usr — creates a chroot where /bin, /sbin and /lib* are ordinary directories, distinct from their counterparts in /usr.
  • --auto-merged-usr — doesn't specify whether /bin, /sbin and /lib* are symlinks to their counterparts in /usr. in that case debootstrap just uses its default behaviour, which is suite-specific. this is the default. 🌸
  • SUITE — the distribution to bootstrap (e.g. ‘stretch’, ‘buster’, ‘bullseye’, ‘sid’). a complete list lives in /usr/share/debootstrap/scripts. 📂
  • TARGET-DIRECTORY — the directory to create the chroot in. it gets created if it doesn't already exist. no worries. ✨
  • 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. (main character energy only for the defaults, honestly.)

💜 sbuild-createchroot behaviour 💜

  • --setup-only — doesn't run debootstrap. only does the setup tasks on an already-existing chroot. super useful for converting an existing chroot for use with sbuild, one you already made with a tool like debootstrap. some configuration steps can only happen on a directory chroot, so heads up: this option is not useful with the unshare backend. 🙃
  • --make-sbuild-tarball=file — creates a bootstrapped file type chroot ready to go with sbuild, and saves it as file. the compression format used for the tarball depends on the file extension you use in file. go check the TARBALL FILE section for the details. 🎁
  • --keep-sbuild-chroot-dir — doesn't delete the directory used for creating a file type chroot. this option does literally nothing if you're not creating a file type chroot. 💀
  • --no-deb-src — doesn't add a deb-src line to the /etc/apt/sources.list file in the TARGET-DIRECTORY after the debootstrap process. useful when you know sbuild will never have to download the source package itself, and is always handed an already-downloaded dsc. in that case this option saves bandwidth and disk space, because the source indices don't have to be downloaded and then continually updated forever and ever. 💾
  • --alias=alias — adds an alternative name the chroot will be known by. you can give this option multiple times to add more than one alias. aliases are great for chroots of distributions known by more than one name — for example, Debian unstable is also known as sid. also, sbuild picks the distribution by the latest changelog entry, which could list UNRELEASED for packages the maintainer is still working on. so for Debian it 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 instead. see the EXAMPLES section for how to actually use this in practice. 🔗
  • --extra-repository=spec — adds 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 let packages in the experimental distribution 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 — sets the chroot command-prefix option as specified. a common use-case is specifying eatmydata, which stops all commands executed in the chroot from syncing data to disk (obsessed 🍽️). this option is only allowed when choosing --chroot-mode=schroot. see schroot.conf(5) for more details.

part 2 is coming bestie, don't go anywhere 🦋✨

🎀 TARBALL FILE 🎀

okay bestie so here's the thing about making an sbuild tarball file — the compression format you get depends entirely on the extension you slap on the filename. no cap. here's the whole detection list and what each one gives you 💅

  • *.tar — gives you an uncompressed tarball. raw. unfiltered. just vibes.
  • *.tar.gz | *.tgz — gives you a compressed tarball using gzip ✨
  • *.tar.bz2 | *.tbz — gives you a compressed tarball using bzip2
  • *.tar.lz | *.tlz — gives you a compressed tarball using lzip
  • *.tar.xz | *.txz — gives you a compressed tarball using xz 🦋
bestie listen. if you specify no extension at all, sbuild-createchroot will literally rename file to file.tar.gz and then generate file.tar.gz as a compressed tarball using gzip. it's giving "i'll do it myself" 😭 gzip is the default, periodt.

🌈 EXAMPLES 🌈

✨ the bootstrapped unstable-with-sbuild-and-schroot situation ✨

to create a bootstrapped file type sid (unstable) chroot that's ready for use with sbuild and schroot (which is the default backend), saved in /srv/chroot/unstable-amd64.tar.gz, using the deb.debian.org Debian http mirror redirector service, and with 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↵

💖 plain schroot energy 💖

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↵

🍓 backports bestie 🍓

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↵

🧚 experimental with a custom prefix 🧚

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↵

👑 no sudo required, main character energy 👑

creating a chroot for the unshare backend does not require superuser privileges (no sudo, bestie!! 🙈). the path for the tarball here is the default path that sbuild actually expects 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 💜

not me giving you the lore but like — sbuild-createchroot was previously known as buildd.chroot. bestie we're talking a full rebrand. 👑

buildd.chroot performed exactly the same tasks, but on top of that it additionally created a number of directories in the chroot for use by sbuild. that part is now the job of schroot(1) — it moved out and honestly it's thriving. 🌸

👑 AUTHORS 👑

  • Roger Leigh.
  • Francesco P. Lovergine.
  • Andres Mejia.

the icons. the legends. 🫶

  • Copyright © 2004 Francesco P. Lovergine <frankie@debian.org>.
  • Copyright © 2007-2008 Roger Leigh <rleigh@debian.org>.
  • Copyright © 2010 Andres Mejia <mcitadel@gmail.com>.

🌸 SEE ALSO 🌸

iykyk, go read those next bestie 💜

okay that's the whole page!! this was Version 0.91.10ubuntu1, dated 29 June 2026, and it's the SBUILD-CREATECHROOT(8) manual — go forth and build chroots, you absolute icon 💅✨🎀

📦 where this page comes from