armbian/build: compiling Debian or Ubuntu images for SBCs from source

What armbian/build is for, and who should clone it

The repository describes itself as the Armbian Linux Build Framework, and its stated purpose is to create customizable OS images based on Debian or Ubuntu for single-board computers and embedded devices. The distinction that matters is between assembling an image and downloading one. The README addresses that directly with a pointer: readers looking for prebuilt images are sent to Armbian Imager, which downloads and flashes Armbian to an SD card or USB drive and is available for Linux, macOS and Windows.

So the audience here is narrower. You are in scope if you need control over versions, configuration, firmware, device trees or system optimizations, which is the list the README gives. That covers a maintainer carrying a board-specific patch, someone testing a kernel change on real hardware, or a team that wants a reproducible image rather than a downloaded artifact. The framework supports native, cross and containerized builds for x86_64, aarch64, armhf and riscv64, and the README says it suits development, testing, production or automation. If your requirement is simply a booting system, none of that machinery buys you anything.

Kernel, bootloader and root filesystem in one build tree

The build produces a complete Linux system: kernel, bootloader and root filesystem, according to the README. The top-level layout shows how that is organized rather than hidden behind a single script. There is a config/ directory, an extensions/ directory for build extensions, a lib/ directory holding the framework logic, packages/ for packaging, a patch/ directory for patches, and tools/ alongside them. compile.sh is the entry point that ties these together.

The Python side is pinned deliberately. requirements.txt opens with a note that versions must always be fixed because this matters for correct hashing, and that Dependabot keeps them current. The list shows what the build touches: pyelftools for building U-Boot, unidiff for parsing unified diff, GitPython for manipulating git repositories, PyYAML for parsing and writing YAML, Jinja2 for templating, dtschema and yamllint for checking dts files and dt bindings, and pylibfdt pinned to an upstream tag with a comment that it fixes breakage from swig-4.5.0. That is the shape of a build system that patches and validates device trees as a first-class step, not an afterthought.

The pinning strategy has a cost worth naming. Because versions are fixed for hashing, the dependency set moves when someone updates the file, not when a new release appears upstream. A contributor who needs a newer library has to change requirements.txt and accept that the hash changes.

Installing the framework and running a first build

The README gives a three-line quick start. It clones the repository, changes into it, and runs the build script. Nothing is installed globally first; the framework lives in the checkout.

git clone https://github.com/armbian/build
cd build
./compile.sh

The README includes an animated demonstration of the build in progress, so the first run is interactive rather than a silent long job. Expect the script to ask what you want to build before it starts compiling.

Before running it, check the host against the stated requirements, because these are not soft. The README asks for at least 8GB of RAM, noting that less is workable with KERNEL_BTF=no, about 50GB of free disk space, and an x86_64, aarch64 or riscv64 architecture. You also need superuser privileges through sudo or root, and the README warns that an outdated system, including outdated Docker, can cause failures.

The operating system options are specific. Native builds target Armbian or Debian 13 (Trixie). Containerized builds run on any Docker-capable Linux. On Windows the supported path is WSL2 with Armbian/Debian 13 (Trixie). There is no documented macOS path in the README, so treat that as out of scope rather than something to improvise.

Python dependencies come from the pinned requirements file, which is why the checkout carries it at the top level:

pip install -r requirements.txt

That file pins pip itself and setuptools alongside the build libraries, and notes that some pip caches omit transitive dependencies, which is why gitdb and smmap are listed explicitly. If a build fails on a missing Python module, this file is the place to look first.

Where the framework gets in your way

The resource floor is the most obvious constraint. Eight gigabytes of RAM and 50GB of disk is a workstation or a well-provisioned VM, not a laptop you happen to have open. The KERNEL_BTF=no escape hatch lowers the memory requirement, but the README does not say by how much, so it is a mitigation rather than a number you can plan against.

The host matrix is the second constraint. Armbian or Debian 13 Trixie for native builds, any Docker-capable Linux for containers, WSL2 with Trixie on Windows. If you run an older Debian or Ubuntu release as your build host, the README does not list it as supported, and it explicitly warns that outdated tooling causes failures. This is a framework that expects a current toolchain and does not spend effort accommodating older ones.

The third is scope. This is the build framework for a distribution, not a general-purpose embedded build system. It exists to produce Armbian images for the boards the configuration covers. If your target is a board outside that set, or you want to assemble a minimal root filesystem without a distribution's conventions layered on top, the framework's assumptions work against you rather than for you. The README does not document a rollback path for a failed build, and it does not promise that every board and branch combination yields a bootable artifact.

armbian/build compared with Yocto or Buildroot

The natural alternative for anyone building a Linux system for an ARM board is Yocto or Buildroot. The difference in approach is what each one starts from.

Yocto and Buildroot begin with recipes and configuration and assemble a distribution to your specification, including the root filesystem contents, the init system and the package set. You define the system; the toolchain produces it. armbian/build begins from Debian or Ubuntu as the base, per the README, and layers a kernel, a bootloader and board-specific tweaks on top. You inherit a distribution's package management and conventions, and you change the parts the framework exposes: kernel configuration, U-Boot handling, firmware, device trees.

That makes armbian/build faster to a working image for a supported board and considerably less work if Debian or Ubuntu is what you wanted anyway. It makes it the wrong tool if you need a root filesystem that is not Debian-derived, or if you need to control package composition at the recipe level. Yocto also carries its own substantial learning curve and build resource requirements; the trade is not one of effort against nothing, but of which layer you want to own. If your board is not in the Armbian configuration set, Yocto or Buildroot is where you would look, because the framework's board support is the thing you would otherwise be writing yourself.

Licence, maintenance and what an upgrade costs you

The repository is licensed GPL-2.0, and the LICENSE file sits at the top level. The practical implication is the usual one for a GPL-2.0 build framework: if you distribute images produced with it, your obligations concern the software you distribute, and if you modify the framework itself and distribute that, the licence follows your changes. That is a general observation about the licence identifier, not legal advice, and anyone shipping a product should read the LICENSE file and take their own advice.

On maintenance, the repository is not archived, and the last push was on 2026-09-22. Recent releases are weekly digests: v26.11.0-trunk.54 on 2026-09-21, v26.11.0-trunk.48 on 2026-09-14, v26.11.0-trunk.40 on 2026-09-07. The version string carries a trunk marker, which tells you these are development builds of the 26.11 line rather than a frozen stable tag.

Upgrading the framework is a git pull, but the cost is not only the diff. Because requirements.txt pins every Python dependency for hashing, a pull that changes that file changes what the build downloads and how artifacts are identified. A pull that changes patch/ or config/ changes what goes into the kernel and the board configuration. If you carry local modifications, you are resolving conflicts in the same tree the framework uses to define its own builds. There is a shell.nix file at the top level for anyone who wants the environment expressed declaratively, and a .pre-commit-config.yaml for contributors, but the README does not describe a supported upgrade procedure for downstream forks.

Editorial conclusion

Adopt armbian/build if you need to change kernel configuration, U-Boot handling, firmware, device trees or board-specific tweaks for a supported single-board computer, and you can give a build host 8GB of RAM and roughly 50GB of free disk. Do not adopt it if you only want a working system on an SD card: the README points that audience at Armbian Imager instead. Before committing, check that your board is covered by the configuration in the repository, confirm your host matches one of the supported options (Armbian/Debian 13 Trixie natively, any Docker-capable Linux in a container, or WSL2 with Trixie on Windows), and run ./compile.sh once to see which artifact your chosen board and branch actually produce.

Frequently asked questions

Official sources

1. armbian/build on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases