Cooking a Debian System with Debos: Declarative Debian Image Building

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

“Cooking a Debian System: One, Two, Debos” is the title of a 2018 Embedded Linux Conference Europe talk—not a Debian release or a separate Debian edition. The subject is Debos, an open-source image builder that turns an ordered YAML recipe into a customized Debian-based root filesystem, archive, or disk image.

Debos is a strong choice when you want Debian packages and compatibility without maintaining a long collection of host-dependent shell scripts. It does not automatically create a bootable image for every board, and its declarative recipes are not automatically bit-for-bit reproducible. Repository state, package versions, timestamps, firmware, bootloaders, and board-specific configuration still matter.

#	Preview	Product	Price
1		Linux Bible	$41.28	Buy on Amazon
2		Debian 13.3 "Trixie" Desktop Handbook: A Practical Guide to Installing, Securing, and Mastering the...	$14.77	Buy on Amazon
3		Linux: QuickStudy Laminated Reference Guide (Quick Study Computer)	$6.95	Buy on Amazon
4		The Debian Linux Guide: Install, Learn and Master Debian 13 Trixie — The Plain English Linux...	$5.99	Buy on Amazon
5		Debian 13 Linux Essentials: Your Complete Guide to Mastering the Latest Debian System with...	$8.99	Buy on Amazon

The short version

A conventional Debian image workflow often looks like this:

1. Run debootstrap to create a basic root filesystem.
2. Enter it with a chroot.
3. Install packages.
4. Copy configuration and application files.
5. Run customization commands.
6. Package the filesystem or place it into a disk image.

Debos coordinates those operations through a YAML recipe. Its actions can bootstrap Debian, install packages, copy files, execute commands, create partitions, deploy filesystems, produce tar archives, install local Debian packages, and work with OSTree. In that sense, Debos does not replace Debian package management or debootstrap; it provides a structured image-building workflow around them.

#1 Best Overall

Sale

Linux Bible

$41.28

Buy on Amazon

The result can be:

• a root filesystem archive for extraction, containers, chroots, or later image assembly;
• a raw disk image with partitions and filesystems; or
• part of a board-ready image, provided that the recipe also handles the target board’s bootloader, kernel, device tree, firmware, and boot configuration.

Install Debos

Debian package

On Debian stable, install the distribution package:

sudo apt update
sudo apt install debos

The Debian stable package page currently lists Debian 13 “Trixie” and Debos version 1.1.5-1+deb13u1 as of August 18, 2026. Check the package page for the version and dependencies available on your release and architecture.

Build from source

The upstream project lists these Debian build dependencies:

sudo apt install golang git libglib2.0-dev libostree-dev 
  qemu-system-x86 qemu-user-static debootstrap systemd-container

One upstream installation approach is:

export GOPATH=/opt/src/gocode
go install -v github.com/go-debos/debos/cmd/debos@latest
/opt/src/gocode/bin/debos --help

@latest is convenient, but it is not a reproducibly pinned build. For production, use a tagged release or commit and record the Go toolchain and dependency versions.

Official container

The project publishes a container image:

docker pull godebos/debos

A current upstream invocation is:

docker run --rm -it 
  --device /dev/kvm 
  --user "$(id -u)" 
  --workdir /recipes 
  --mount "type=bind,source=$(pwd),destination=/recipes" 
  --security-opt label=disable 
  godebos/debos example.yaml

The mounted directory supplies the recipe and receives artifacts. The container needs access to /dev/kvm when using the KVM fakemachine backend. On hosts where the current user cannot access that device, add its owning group:

--group-add "$(stat -c '%g' /dev/kvm)"

Write a minimal Debian recipe

A current minimal example can build an ARM64 Debian 13 root filesystem archive:

{{- $image := or .image "debian.tgz" -}}
architecture: arm64

actions:
  - action: debootstrap
    suite: trixie
    components:
      - main
      - non-free-firmware
    mirror: https://deb.debian.org/debian
    variant: minbase

  - action: apt
    packages:
      - sudo
      - openssh-server
      - adduser
      - systemd-sysv
      - firmware-linux

  - action: run
    chroot: true
    command: echo debian > /etc/hostname

  - action: pack
    file: {{ $image }}
    compression: gz

Save it as example.yaml and run:

debos example.yaml

To choose another output name without editing the recipe:

Rank #2

Debian 13.3 "Trixie" Desktop Handbook: A Practical Guide to Installing, Securing, and Mastering the Debian Linux Desktop - From Install to Advanced Administration (The Modern Linux Mastery Series)

$14.77

Buy on Amazon

debos -t image:"debian-arm64.tgz" example.yaml

The output is a gzip-compressed tar archive. It is not a bootable SD-card image.

What each field does

• architecture: arm64 selects the target architecture.
• suite: trixie selects the Debian suite. Change this deliberately rather than copying an old example’s suite.
• components selects repository sections. non-free-firmware is important for many modern hardware targets.
• mirror identifies the Debian package mirror.
• variant: minbase requests a relatively minimal bootstrap.
• apt installs packages into the target filesystem.
• run executes a command; chroot: true makes the command run in the target root filesystem.
• pack creates the final tar archive.
• The Go-template expression lets the image name be overridden with -t.

Understand the action model

Debos recipes contain an optional architecture, variables and templates, and an ordered actions list. Actions run sequentially, so later steps can build on files and packages created earlier.

For exact action fields, consult the upstream documentation and the referenced action documentation. Syntax varies by action, and a conceptual pipeline should not be mistaken for a universal board image recipe.

From a root filesystem to a bootable image

There are three materially different outputs:

1. Root filesystem archive: a tarball that can be extracted or used as an input to another system.
2. Raw disk image: an image file containing a partition table and filesystems.
3. Board-ready boot media: an image tailored to a particular board’s boot chain and hardware.

A disk-image recipe may conceptually contain steps like these:

actions:
  - action: image
    imagename: board.img
    size: 2G

  - action: image-partition
    imagename: board.img
    partition: boot
    start: 4M
    end: 256M
    filesystem: vfat

  - action: image-partition
    imagename: board.img
    partition: root
    start: 256M
    end: 100%
    filesystem: ext4

  - action: filesystem-deploy
    image: board.img
    partition: root

Verify the exact syntax against the action documentation and a recipe for the specific board. A truly bootable product may additionally require:

• a compatible bootloader installed at the correct location;
• a kernel and initramfs;
• a device tree;
• firmware and board-specific packages;
• the correct partition flags and filesystem UUIDs;
• console, root-device, and boot-argument configuration; and
• vendor-specific flashing or first-boot steps.

The debos-recipes repository includes examples for Raspberry Pi 3, 64-bit Raspberry Pi images, Libre Computer Le Potato, and other Debian ARM systems. Those examples span older Debian releases, so review their suites, kernels, package names, and assumptions before reuse.

Fakemachine, isolation, and build behavior

Unless disabled, Debos uses fakemachine to execute recipe actions in a virtualized build environment. This reduces dependence on the host filesystem and helps make builds more consistent across machines.

Rank #3

Linux: QuickStudy Laminated Reference Guide (Quick Study Computer)

• Brand new
• box27

$6.95

Buy on Amazon

Useful backend options include:

debos --fakemachine-backend=auto recipe.yaml
debos --fakemachine-backend=kvm recipe.yaml
debos --fakemachine-backend=qemu recipe.yaml
debos --disable-fakemachine recipe.yaml

auto is the default selection behavior. If no supported backend is available, Debos may fall back to host execution. That fallback can weaken isolation and reproducibility.

The Debian manpage reports historical timings for one Pine A64 recipe on an Intel Pentium G4560T with an SSD:

These are historical, hardware-specific figures from the manpage, not general benchmarks. KVM is usually the practical choice when available; QEMU is more portable but can be much slower. Avoid disabling fakemachine casually, particularly for untrusted recipes.

Cross-architecture builds are not hardware testing

Setting architecture: arm64 can construct an ARM64 filesystem on an AMD64 host. QEMU user-mode emulation and a suitable system-emulation backend may be needed, and package maintainer scripts can execute under emulation.

That is useful, but it is not equivalent to compiling every component from source or testing the finished system on ARM64 hardware. Emulation can be slower and occasionally expose compatibility problems. It also cannot validate the target board’s:

• boot ROM and bootloader behavior;
• device tree and peripheral configuration;
• GPU, Wi-Fi, and Bluetooth drivers;
• power management and timing;
• storage behavior; or
• firmware and board-specific boot configuration.

A successful build means that the recipe completed. It does not prove that the image will boot on the board.

Debian suites, repositories, and firmware

The example uses Debian 13 “Trixie”, main, and non-free-firmware. The suite determines the Debian release or development branch; components determine which repository sections are available; and the mirror determines where packages are downloaded.

Rank #4

The Debian Linux Guide: Install, Learn and Master Debian 13 Trixie — The Plain English Linux Handbook for Everyday Users

$5.99

Buy on Amazon

For long-lived builds, control those inputs. A moving suite, changing mirror contents, unpinned package versions, or a source archive downloaded by a script can produce different images from the same YAML. Declarative syntax improves repeatability, but it does not by itself guarantee bit-for-bit reproducibility.

Other uncontrolled inputs can include timestamps, generated files, locale, timezone, kernel and initramfs inputs, package metadata, signing-key state, and the Debos or dependency versions. Record the recipe, Debos version, repository configuration, package metadata, source checksums, and output checksum in CI.

Useful command-line controls

These options are especially useful during development and diagnosis:

debos --dry-run --print-recipe recipe.yaml
debos --verbose --debug-shell recipe.yaml

• --dry-run validates and composes the recipe without performing the actual build.
• --print-recipe shows the composed recipe after template processing.
• --verbose increases diagnostic output.
• --debug-shell can provide an interactive shell when an action fails.
• --show-boot displays boot output from the fakemachine.
• --scratchsize=SIZE, --cpus=N, and --memory=SIZE tune the build environment.
• --artifactdir=DIR selects an artifact directory.
• --template-var=NAME:VALUE supplies a recipe template variable.
• --environ-var=NAME:VALUE passes an environment variable.
• --version records the Debos version used for a build.

Troubleshooting

KVM is missing or inaccessible

Check the device and your group membership:

ls -l /dev/kvm
id

In a container, pass --device /dev/kvm and, if necessary, the device’s owning group. If KVM is unavailable, try:

debos --fakemachine-backend=qemu recipe.yaml

QEMU may work without KVM but can be substantially slower. --disable-fakemachine may require root privileges and removes the isolation provided by virtualization.

Packages cannot be downloaded

Check the suite name, target architecture, mirror availability, repository components, DNS, and proxy configuration. A proxy that is reachable as localhost from the host is generally not reachable as localhost from inside the fakemachine. Use a network-reachable host address instead.

Debos propagates common proxy variables, including http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, and no_proxy. Scripts inside the target may still require their own proxy configuration.

Best Value

Debian 13 Linux Essentials: Your Complete Guide to Mastering the Latest Debian System with Confidence (2026 Edition)

$8.99

Buy on Amazon

The same recipe behaves differently on two hosts

Compare backend selection, root versus non-root execution, mounted files, environment variables, locale, timezone, network access, mirror contents, QEMU/KVM availability, ownership, permissions, and unpinned packages. Start with:

debos --print-recipe --verbose recipe.yaml

Then fix inputs rather than relying on a more privileged host. CI builds on controlled workers can expose host dependencies early.

The image builds but will not boot

Confirm the architecture, partition table, partition flags, bootloader location, kernel, initramfs, device tree, firmware, console configuration, root filesystem UUID or device path, and board-specific boot files. Test with a serial console where possible. A root filesystem archive can be perfectly valid while being unusable as boot media.

Security considerations

Recipes can run commands in the target filesystem and, depending on configuration, in the build environment or on the host. Treat recipes, overlays, downloaded packages, and source archives as code-execution inputs.

• Review third-party recipes before running them.
• Pin source URLs and verify checksums where supported.
• Keep secrets out of recipes and generated images.
• Do not run untrusted recipes with --disable-fakemachine.
• Use isolated CI workers for untrusted contributions.
• Separate build credentials from runtime credentials.
• Verify image checksums and contents before deployment.

Debos compared with related tools

These tools are adjacent rather than interchangeable. Debian’s package listing identifies several of them, but the right choice depends on whether the product needs Debian compatibility, a specialized BSP ecosystem, a minimal non-Debian firmware, BitBake integration, or cloud-image tooling.

Who should use Debos?

Choose Debos when the base system should remain Debian-compatible, package installation and ordinary filesystem customization dominate the workflow, and the team wants a readable YAML recipe that can run locally or in CI. It is particularly well suited to embedded appliances, development boards, custom ARM images, and systems that need several related image variants.

Look elsewhere when you need an extensive distribution-engineering ecosystem, highly specialized board-support integration, a build system centered on source compilation rather than Debian packages, or an OTA and fleet-management platform. Debos creates images; it is not an OTA service, compliance platform, or universal desktop/live-installer generator.

Bottom line

Debos is best understood as a recipe-driven orchestration layer for building Debian-based systems. It offers a cleaner and more repeatable alternative to an expanding collection of debootstrap and shell commands, while retaining Debian’s package ecosystem. Start with a root filesystem archive, pin the inputs that matter, use KVM-backed fakemachine builds where practical, and treat bootloader, kernel, firmware, and real-device validation as separate board-specific work.

The original 2018 talk remains a useful introduction to the idea. For current work, use the upstream Debos documentation, current Debian package metadata, and a maintained recipe for your actual target rather than copying historical suite names or kernel assumptions.

Quick Recap

SaleBestseller No. 1

Linux Bible

$41.28

Bestseller No. 2

Debian 13.3 "Trixie" Desktop Handbook: A Practical Guide to Installing, Securing, and Mastering the Debian Linux Desktop - From Install to Advanced Administration (The Modern Linux Mastery Series)

$14.77

Bestseller No. 3

Linux: QuickStudy Laminated Reference Guide (Quick Study Computer)

Brand new; box27

$6.95

Bestseller No. 4

The Debian Linux Guide: Install, Learn and Master Debian 13 Trixie — The Plain English Linux Handbook for Everyday Users

$5.99

Bestseller No. 5

Debian 13 Linux Essentials: Your Complete Guide to Mastering the Latest Debian System with Confidence (2026 Edition)

$8.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.