mmdebstrap

Create a Debian Stable directory chroot

$ sudo mmdebstrap stable [path/to/debian-root]/

$ mmdebstrap bookworm [path/to/debian-bookworm.tar] [http://mirror.example.org/debian]

$ mmdebstrap sid [path/to/debian-sid.tar] --include=[pkg1,pkg2]

mmdebstrap [OPTION...] SUITE TARGET [MIRROR...]

-a ARCH, --arch=ARCH
    Specify the architecture of the target system (e.g., amd64, arm64). This is crucial for cross-architecture builds.

--foreign
    Perform a 'foreign' bootstrap, where the target architecture is different from the host. This implies that the final dpkg --configure -a step must be run within the target architecture's environment (e.g., via qemu-user-static).

--unpack-foreign
    In a 'foreign' bootstrap, this option causes mmdebstrap to unpack all packages on the host system. This can be faster but requires qemu-user-static to be correctly set up for cross-unpacking.

--variant=NAME
    Select a bootstrap variant. Common variants include minbase (minimal system), buildd (for package building), or essential (only essential packages). Defaults to minbase.

--include=PKG1,PKG2,...
    Specify a comma-separated list of packages to install in addition to the default set for the chosen variant.

--exclude=PKG1,PKG2,...
    Specify a comma-separated list of packages to exclude from the installation, even if they would normally be included by the chosen variant or dependencies.

--components=COMP1,COMP2,...
    Specify the APT components to enable (e.g., main, contrib, non-free). Defaults to main.

--keyring=FILE
    Use an alternative keyring file instead of the default debian-archive-keyring.gpg. Useful for custom repositories.

--setup-hook=SCRIPT
    Execute a shell script SCRIPT inside the chroot before the packages are unpacked. This allows for early customization, like adding custom APT sources or debconf preseeds.

--customize-hook=SCRIPT
    Execute a shell script SCRIPT inside the chroot after all packages have been unpacked and configured. This is ideal for post-installation setup, like creating users, configuring networking, or installing additional software.

--format=FORMAT
    Specify the output format for the bootstrap. Supported formats include tar (default), tar.gz, tar.bz2, tar.xz, squashfs, ext2, ext3, ext4, and null (for temporary chroot).

--output=FILE
    Write the output to FILE instead of standard output (for tar formats) or a generated filename (for image formats). Required for image formats.

--apt-option=OPTION
    Pass an arbitrary option string directly to apt (e.g., -o Acquire::ForceIPv4=true).

--dpkg-foreign-architecture=ARCH
    Add a foreign architecture to dpkg within the target chroot. Useful for multi-architecture builds where you want to install packages for another architecture later.

--chroot
    Instead of creating an archive or image, keep the chroot directory at the specified TARGET path. This allows for direct interaction with the bootstrapped system.

--skip=STAGE
    Skip a specific stage of the bootstrap process. Can be used multiple times. Stages include extract, setup, install, configure, cleanup.

--verbose
    Increase verbosity of output, showing more details about the bootstrap process.

mmdebstrap is a versatile and powerful tool designed to create minimal Debian, Ubuntu, or other derivative root filesystems. It serves as a more advanced and flexible alternative to the traditional debootstrap utility. Unlike its predecessor, mmdebstrap offers robust support for multi-architecture chroots and images, allowing users to bootstrap systems for different CPU architectures (e.g., ARM64 on an AMD64 host) seamlessly using qemu-user-static.

It can fetch packages from multiple APT sources, including official mirrors, local repositories, or apt-cacher-ng, providing extensive control over the package fetching process. Users can specify exact package lists to include or exclude, pre-seed debconf settings, and execute custom shell scripts at various stages of the bootstrap process via powerful hook mechanisms. The output can be directed to a directory (for a chroot), or various archive formats like tarballs, squashfs images, or ext2/3/4 filesystem images. Its reliability and advanced features make it an invaluable tool for building custom container images, virtual machines, and reproducible build environments.

Running mmdebstrap typically requires root privileges to create and populate the target filesystem. It can consume significant disk space and network bandwidth, especially when bootstrapping multiple architectures or large package sets. Proper setup of essential tools like qemu-user-static (for cross-architecture bootstrapping) and sufficient disk space are critical for successful operation. Errors can occur if APT mirrors are unreachable or package dependencies are not resolvable.

The --setup-hook and --customize-hook options are incredibly powerful for tailoring the bootstrapped system. These options allow users to inject custom shell scripts that run within the chroot at critical points: setup-hook before packages are unpacked, and customize-hook after all packages are installed and configured. This enables complex customizations such as adding new repositories, configuring system services, creating users, or installing software not available through standard APT packages.

One of mmdebstrap's standout features is its native support for multi-architecture bootstrapping. By leveraging qemu-user-static, it can create a root filesystem for an ARM64 system on an AMD64 host, for example. This is invaluable for embedded systems development, cross-compilation environments, and building container images for diverse architectures without needing native hardware, significantly streamlining development and deployment workflows.

mmdebstrap was developed as a more modern and robust alternative to the venerable debootstrap utility. It emerged to address several limitations of debootstrap, particularly its less flexible handling of multi-architecture builds, its limited support for complex APT source configurations, and the lack of fine-grained control over the bootstrap stages. The 'mm' in its name often stands for 'multi-mirror' or 'many-mode', reflecting its ability to use multiple APT mirrors and support various output formats and customization options. It has become a preferred tool in the Debian and Ubuntu ecosystems for creating reproducible, minimal, and highly customized root filesystems, especially in automated build pipelines and containerization workflows.

debootstrap(8), chroot(1), dpkg(8), apt(8), qemu-user-static(1), schroot(1)