debootstrap
Create basic Debian/Ubuntu system from scratch
TLDR
Create a Debian stable release system inside the debian-root directory
Create a minimal system including only required packages
Create an Ubuntu 20.04 system inside the focal-root directory with a local mirror
Switch to a bootstrapped system
List available releases
SYNOPSIS
debootstrap [OPTION]...
PARAMETERS
The Debian/Ubuntu release codename (e.g., stretch, bionic, jammy).
The directory where the new system will be installed.
[MIRROR_URL]
(Optional) The URL of the Debian/Ubuntu archive mirror to use. Defaults to http://deb.debian.org/debian.
[SCRIPT]
(Optional) A script or script fragment to execute inside the chroot after the first stage of bootstrapping.
--arch=
Specifies the architecture for the new system (e.g., amd64, arm64).
--foreign
Performs a two-stage bootstrap, necessary for cross-architecture installations. The second stage must be run manually.
--variant=
Selects a variant of the bootstrap (e.g., minbase for a minimal base system, buildd for a build environment).
--include=
Comma-separated list of additional packages to install into the new system.
--exclude=
Comma-separated list of packages to exclude from installation.
--components=
Comma-separated list of archive components to include (e.g., main, contrib, non-free).
--keyring=
Use a specific GPG keyring file instead of the default for signature checking.
--no-check-gpg
Skips GPG signature checking of downloaded Release files. Use with caution.
--no-resolve-deps
Does not resolve recommends/suggests, only strict dependencies. Useful for very minimal installs.
--merged-usr
Creates a merged /usr directory structure (where /bin, /sbin, /lib are symlinks to their /usr counterparts).
--no-same-owner
Prevents debootstrap from attempting to preserve ownership of extracted files during unpacking, useful for specific filesystem types.
DESCRIPTION
debootstrap is a utility that creates a minimal Debian or Debian-based (like Ubuntu) system into a target directory. It achieves this by downloading packages from a specified mirror, unpacking them, and setting up a basic root filesystem. Unlike a full operating system installation, debootstrap does not install a kernel or bootloader; it focuses solely on populating a directory with the necessary userspace binaries and libraries to make it a self-contained Debian environment. This process is commonly referred to as "bootstrapping."
It's widely used for various purposes, including creating chroot environments for software compilation or testing, building custom live CDs or installation images, setting up containers (like LXC), or preparing a system for a full installation where specific packages are desired from the outset. The tool handles dependency resolution and ensures that the core dpkg and apt utilities are functional within the new environment, allowing further package management to be performed inside the bootstrapped system. Its simplicity and effectiveness make it a fundamental tool for Debian-based system administrators and developers.
CAVEATS
debootstrap requires root privileges to run.
It necessitates network access to download packages from mirrors.
It does not install a kernel or bootloader; the bootstrapped system is not directly bootable on bare metal.
The --foreign option requires a manual second stage to be run inside the chroot environment after the initial debootstrap execution.
By default, it uses a generic mirror; specifying a closer, local mirror can significantly speed up the process.
<B>TYPICAL USAGE SCENARIO:</B>
The most common use case for debootstrap is to create a lightweight, isolated Debian environment. For example, to build a chroot jail for software development or testing:
sudo debootstrap jammy /mnt/new_root http://archive.ubuntu.com/ubuntu
sudo chroot /mnt/new_root /bin/bash
This allows one to work within a clean Ubuntu Jammy system without affecting the host operating system, which is invaluable for compiling specific software versions or testing new configurations.
HISTORY
debootstrap was initially developed by Adam Heath for Debian and has been a fundamental tool for creating minimal Debian systems since its inception. It quickly became the go-to utility for bootstrapping new installations, particularly for chroot jails, custom system images, and later, container environments like LXC. Its design was simple and robust, allowing for reliable creation of a base system by downloading and unpacking .deb packages directly, setting the stage for apt and dpkg to take over. Its functionality is often a precursor to more complex system setups, providing a stable foundation for further customization and deployment.
SEE ALSO
chroot(1), apt(8), dpkg(1), mmdebstrap(1)