helpful-tools

Building Armbian for SBCs

Edited Mar 2026

Armbian is an open souce debian-based linux distro designed for ARM and RISC-V SBCs with good community support and documentation. If you’ve purchased a Raspberry Pi alternative such as and Orange Pi or Radxa board I recommend Armbian for the support and documentation.

Prebuilt Images vs. DIY Building

Armbian offers hundreds of prebuilt images on the Armbian download page and even provides an imaging tool similar to Raspberry Pi imager at https://imager.armbian.com.

In most cases you can find a build that fits your needs here but in other cases you will need to build your own image. In my case I want a headless build featuring standard cli tools for the Radxa Zero 2 so I will be building my own image.

Building Armbian

Official Armbian Documentation: https://docs.armbian.com/Developer-Guide_Overview/

1. Install Prerequisites Install coreutils

# MacOS
brew install coreutils

# Debian / Ubuntu
apt update
apt install coreutils

If you are not using Ubuntu you will also need Docker. MacOS & Windows: https://docker.com Debian: https://docs.docker.com/engine/install/debian/

2. Clone Armbian Build Repository Armbian Build Repository: https://github.com/armbian/build

git clone https://github.com/armbian/build.git

3. Generate Targets & Config Files This command generates several configuration files as well as a CSV listing all supported build targets.

cd build
./compile.sh inventory-boards

Note: inventory-boards will take a while to run

4. Modify Build Configuration Identify your board’s build target identifier in ./output/info/boards-inventory.csv generated by the previous command. I find grep helpful for this.

grep radxa output/info/boards-inventory.csv

Then, modify ./userpatches/config-example.conf to specify your board target and desired Debian version.

nano userpatches/config-example.conf

Armbian config documentation: https://docs.armbian.com/Developer-Guide_Build-Switches/

BOARD=radxa-zero2    # Build for the Radxa Zero 2
BRANCH=current
RELEASE=trixie       # Use Debian 13 Trixie
KERNEL_CONFIGURE=no
INSTALL_HEADERS=yes
SHARE_LOGS=no        # Optional log sharing
BUILD_DESKTOP=no
BUILD_MINIMAL=no

5. Modify First Boot Configuration This configuration is read during the device fist boot to connect to your WiFi and provision user accounts.

Create firstboot.conf file & paste template from Armbian autoconfig documentation: https://docs.armbian.com/User-Guide_Autoconfig/

nano userpatches/firstboot.conf

#/root/.not_logged_in_yet
# Network Settings
PRESET_NET_CHANGE_DEFAULTS="1"
## Ethernet
PRESET_NET_ETHERNET_ENABLED="1"     #   Ignored due to WiFi
## WiFi
PRESET_NET_WIFI_ENABLED="1"
PRESET_NET_WIFI_SSID="MyWifi"
PRESET_NET_WIFI_KEY="WifiPassword"
PRESET_NET_WIFI_COUNTRYCODE="US"
PRESET_CONNECT_WIRELESS="y"

# System
SET_LANG_BASED_ON_LOCATION="y"
PRESET_LOCALE="en_US.UTF-8"
PRESET_TIMEZONE="Etc/UTC"

# Root
PRESET_ROOT_PASSWORD="root-password"
PRESET_ROOT_KEY=""

# User
PRESET_USER_NAME="andrew"
PRESET_USER_PASSWORD="password"
PRESET_USER_KEY="https://github.com/azroberts8.keys"  # Pulls SSH keys from your GitHub
PRESET_DEFAULT_REALNAME="Andrew Roberts"
PRESET_USER_SHELL="bash"

6. Compile the Image

./compile.sh example

Note: This will take a long time - you are building the linux kernel

Your compiled image will be saved in ./output/images

Flashing Armbian

1. Connect Device or Flash Memory Connect your board or SD card to your machine and identify its location

# MacOS - should resemble /dev/disk<n>
diskutil list

# Linux - should resemble mmcblk<n>
lsblk

Make sure to identify the correct device before the next step!

2. Flash Image to Device

sudo dd bs=1M status=progress \
if=./output/images/<your-image>.img \
of=/dev/<your-device>

First Boot Setup

1. Boot Your Board Insert your flashed SD card into your board and connect it to power. For you initial boot it may take a couple minutes before it boots and authenticates with your WiFi network.

2. Identify Device on Network Typically your device hostname should be the same as the build target (in my case radxa-zero2). If you are having trouble finding it use arp to list the devices on your LAN

arp -a

3. SSH to Board Root Despite setting a user account and root password in the first-boot configuration, you will need to first SSH to root using the password 1234

ssh root@radxa-zero2

After your connect it will automatically configure the user account and root passwords that you set. Every subsequent sign-on use the root password or user account that you set in the configuration file.