Back to Commands

debootstrap

systemlinux
The debootstrap command is one of the most frequently used commands in Linux/Unix-like operating systems. debootstrap The debootstrap command is used to install a basic Debian or Ubuntu system into a subdirectory of another, already installed system. It can be used to create a chroot environment, a container base image, or the first stage of a Debian-based operating system installation.
See ExamplesView Syntax

Quick Reference

Command Name:

debootstrap

Category:

system

Platform:

linux

Basic Usage:

debootstrap --arch=amd64 bullseye /mnt/debian

Common Use Cases

  • 1

    Chroot environment creation

    Create a basic Debian/Ubuntu system in a subdirectory

  • 2

    Container setup

    Prepare base filesystem for containers or virtual machines

  • 3

    Cross-distribution development

    Set up development environments for different Debian versions

  • 4

    System recovery

    Create a minimal system for recovering damaged installations

Syntax

debootstrap [options] suite target [mirror [script]]

Options

Option Description
--arch=ARCH Set the target architecture (e.g., amd64, arm64, i386)
--components=COMPONENTS Comma-separated list of components to use (e.g., main,contrib,non-free)
--debian-installer Set up for use by the Debian Installer
--exclude=PACKAGES Comma-separated list of packages to exclude
--foreign Do the installation for first stage only (for cross-architecture installs)
--include=PACKAGES Comma-separated list of packages to include
--keyring=FILE Use FILE as the keyring for package verification
--merged-usr Use a merged-/usr system setup
--no-check-gpg Skip GPG verification of Release files
--no-merged-usr Avoid using a merged-/usr system setup
--print-debs Print the packages to be installed
--second-stage Run second stage of the installation (after --foreign)
--variant=VARIANT Set installation variant (minbase, buildd, fakechroot, etc.)
--verbose Verbose output

Examples

How to Use These Examples

The examples below show common ways to use the debootstrap command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

#

Basic Examples:

# Install a minimal Debian stable system in /mnt/debian
sudo debootstrap stable /mnt/debian http://deb.debian.org/debian/
# Install Ubuntu jammy (22.04) in /mnt/ubuntu sudo debootstrap jammy /mnt/ubuntu http://archive.ubuntu.com/ubuntu/
# Install Debian bookworm with specific architecture sudo debootstrap --arch=arm64 bookworm /mnt/debian-arm64 http://deb.debian.org/debian/
# Create minimal installation with fewer packages sudo debootstrap --variant=minbase bullseye /mnt/debian-minimal

Advanced Examples:

# Install Debian unstable with components
sudo debootstrap --components=main,contrib,non-free unstable /mnt/debian-unstable
# Use a different keyring file sudo debootstrap --keyring=/path/to/custom-keyring.gpg stable /mnt/debian
# Create foreign architecture installation sudo debootstrap --foreign --arch=arm64 bullseye /mnt/debian-arm64 # Second stage of foreign architecture installation (run inside chroot/target) sudo chroot /mnt/debian-arm64 /debootstrap/debootstrap --second-stage # Use a specific include and exclude set of packages sudo debootstrap --include=ssh,vim,curl --exclude=nano bullseye /mnt/debian-custom # Create a Debian system with a specific mirror and script sudo debootstrap --arch=amd64 sid /mnt/debian-sid http://deb.debian.org/debian sid

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

Suites/Distributions:

Common Debian and Ubuntu release code names that can be used with debootstrap:

  • Debian: stable, testing, unstable, sid, bookworm, bullseye, buster, stretch
  • Ubuntu: noble, jammy, focal, bionic, xenial

Installation Variants:

Different installation variants offer different package sets:

  • minbase: Only essential packages and apt
  • buildd: Minimal build environment
  • fakechroot: Used for building without root privileges
  • default: Standard system

Cross-Architecture Installation:

To install for a different architecture than the host:

  1. Use --foreign and --arch options for the first stage
  2. Copy qemu-user-static for the target architecture into the target directory if needed
  3. Chroot into the target directory
  4. Run debootstrap --second-stage

Common Use Cases:

  • Chroot environments: For development, testing, or isolation
  • Container base images: Creating custom Docker/LXC/LXD images
  • System recovery: Repairing a broken system by installing a fresh base
  • Custom installations: First step in a custom system setup
  • Cross-distribution development: Testing software on different distributions

Post-Installation Configuration:

After running debootstrap, you'll typically need to:

  1. Configure /etc/fstab inside the target
  2. Set up networking configuration
  3. Configure timezone and locale settings
  4. Set up users and passwords
  5. Install additional packages as needed

Requirements:

  • Root privileges (sudo) are typically required
  • Internet connection to download packages (unless using a local mirror)
  • Sufficient disk space for the base installation
  • For cross-architecture installs, appropriate qemu-user-static packages

Tips & Tricks

1

Use the --arch architecture option to specify the target architecture

2

Use the --variant variant option to specify the variant of the distribution

3

Use the --include package option to include additional packages

4

Use the --exclude package option to exclude packages

5

Use the --no-check-gpg option to skip GPG signature verification

Common Use Cases

Chroot environment creation

Create a basic Debian/Ubuntu system in a subdirectory

Container setup

Prepare base filesystem for containers or virtual machines

Cross-distribution development

Set up development environments for different Debian versions

System recovery

Create a minimal system for recovering damaged installations

OS image creation

Generate base images for embedded systems or custom installations

Related Commands

These commands are frequently used alongside debootstrap or serve similar purposes:

Explore All Commands

Use Cases

1

Chroot environment creation

Create a basic Debian/Ubuntu system in a subdirectory

2

Container setup

Prepare base filesystem for containers or virtual machines

3

Cross-distribution development

Set up development environments for different Debian versions

4

System recovery

Create a minimal system for recovering damaged installations

5

OS image creation

Generate base images for embedded systems or custom installations

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the debootstrap command works in different scenarios.

See ExamplesTry Lab Exercises
$ debootstrap
View All Commands