FlatRoot

Build Linux root filesystem directories from official distribution packages — without root privileges or a running package manager.

---

FlatRoot is a tool that builds Linux root filesystem directories from official distribution packages — without root privileges or a running package manager. It resolves dependencies, fetches archives from distribution mirrors, extracts them into a target directory, and runs post-install scripts inside a namespace sandbox.

The sections below organise the documentation by intent — the Diátaxis modes (Tutorials, How-To Guides, Reference, Explanation), plus an Architecture section on FlatRoot's internal design. Each has a different purpose — pick the one that matches what you need right now.

Tutorials

Hands-on lessons for newcomers.

• Build your first rootfs — assemble a miniature Alpine Linux in five minutes.
• Reproducible Builds — compile a program twice against a pinned toolchain and see the bytes match.

How-To Guides

Task-oriented recipes for practitioners.

• Get FlatRoot — How to install FlatRoot on your machine.
• Install packages — How to put packages from a distribution into a rootfs directory.
• Query packages — How to discover what a distribution offers and look up details about any of its packages.
• Pin a build to a snapshot date — How to make a build reproducible so the same command produces the same rootfs months from now.
• Build for multiple architectures — How to combine packages for different CPU architectures in a single rootfs.

Reference

Tables, flags, and other reference material.

• CLI — Complete reference for every command and option, plus how distribution sources are named on the command line.
• Environment — Every environment variable FlatRoot reads on startup and the fixed environment it sets inside the install sandbox.
• Cache — What FlatRoot stores on disk between runs, where it lives, and how to clean it up.
• Database — The package database FlatRoot builds for each distribution and how to query it directly.
• Path Index — The lookup that answers "which package owns this file?"
• Rootfs Metadata — The on-disk .flatroot/ format: fields, checksum algorithms, and reinstallation behaviour.
• deb — The index and archive layout for Debian and Ubuntu packages.
• rpm — The index and archive layout for CentOS, Fedora, AlmaLinux, Rocky, and openSUSE packages.
• pacman — The index and archive layout for Arch Linux and CachyOS packages.
• apk — The index and archive layout for Alpine Linux packages.

Explanation

Explanations of how and why FlatRoot works the way it does.

• Overview — A guided tour of how FlatRoot turns a list of package names into a working rootfs.
• The distro abstraction — How one pipeline serves ten distributions by hiding distro specifics behind a single trait.
• The seed list — Why the install set starts from more than the names you typed.
• Dependency resolution — How the resolver turns a seed list into the complete, ordered install closure.
• Virtual names and providers — How declared names that aren't real packages map to the package that provides them.
• Conditional dependencies — How RPM rich deps and Alpine install-if triggers are evaluated against the install set.
• The sandbox — How package post-install scripts run unprivileged, without real root or a live system.
• Cache regeneration — How FlatRoot rebuilds the runtime caches — fonts, icons, MIME types, and so on — that applications expect to find inside a rootfs.
• The metadata layer — The bookkeeping FlatRoot writes alongside every installed rootfs and what each piece is used for.
• Cross-distro boundaries — Why FlatRoot refuses to mix packages from different sources into one rootfs.
• Multiarch — How packages for multiple CPU architectures share a single rootfs tree.

Architecture

How FlatRoot is built internally.

• Overview — The ordered pipeline of stages that turns a request into a finished rootfs.
• CLI Design — Why FlatRoot's commands and options look the way they do, and which CLI conventions the design follows.
• Packages — How the codebase is organized into packages and what each is responsible for.
• Spec — The behavioural specification: one page per use case, recording what the tool promises and how the promise travels through the packages.