How to Use the OpenWrt ImageBuilder

ImageBuilder is suitable only when its version, target, subtarget, and profile match the router. Never use an ImageBuilder for another model.

What is ImageBuilder?

ImageBuilder is a precompiled environment for quickly creating a customized firmware image from packages already available in the repository. It can add or remove packages, add configuration files, and create a flashable image without compiling all of OpenWrt from source.

If you need to modify the kernel, drivers, target, or a package that has no matching binary, use the full source build system instead.

Choose the correct ImageBuilder

Identify:

OpenWrt version.
Target System.
Subtarget.
Target Profile.
CPU architecture.

These values must match the router. Start at the official download site:

https://downloads.openwrt.org/

Then follow:

releases/<version>/targets/<target>/<subtarget>/

ImageBuilder filenames normally include the version, target, and architecture. Do not choose based only on the router’s commercial name.

Extract ImageBuilder

For a .tar.zst archive:

mkdir -p ~/openwrt-imagebuildercd ~/openwrt-imagebuildertar --use-compress-program=unzstd \  -xf openwrt-imagebuilder-*.tar.zstcd openwrt-imagebuilder-*/

If unzstd is missing:

sudo apt updatesudo apt install -y zstd

View profiles and available packages

Run:

make info

This shows the supported profiles and packages for the selected repository. If the router model is missing, stop and download the correct ImageBuilder.

Add packages

For example:

make image \  PROFILE="<router-profile>" \  PACKAGES="luci luci-ssl htop tcpdump"

Replace <router-profile> with the exact profile returned by make info.

Remove a default package by prefixing its name with -:

make image \  PROFILE="<router-profile>" \  PACKAGES="luci -ppp"

Do not remove a package until you know whether it is a dependency of networking, storage, or recovery.

Add configuration files with FILES

Create the files/ tree:

mkdir -p files/etc/uci-defaultsmkdir -p files/etc/config

For example:

cat > files/etc/banner <<'EOF'AIoT.IO.VN - OpenWrt custom imageEOF

Build with:

make image \  PROFILE="<router-profile>" \  PACKAGES="luci" \  FILES="files"

For real work, create files with an editor and inspect them before building. Scripts in etc/uci-defaults should be executable and idempotent.

Set an output directory and inspect logs

mkdir -p outputmake image \  PROFILE="<router-profile>" \  PACKAGES="luci" \  FILES="files" \  BIN_DIR="output"

For verbose output:

make V=s image PROFILE="<router-profile>" PACKAGES="luci"

The image is normally placed in output/ or bin/, depending on the ImageBuilder version and options.

ImageBuilder versus a source build

Criteria	ImageBuilder	Build system
Speed	Fast	Slower
Add available binary packages	Yes	Yes
Add configuration files	Yes	Yes
Modify kernel/driver	Not suitable	Yes
Modify package source	Not suitable	Yes
Resource requirement	Lower	Higher

Flash checklist

Correct OpenWrt version.
Correct target and subtarget.
Correct profile.
Correct image type: factory, sysupgrade, or recovery.
Configuration backup.
Router-specific flashing guide.
Recovery method if the image does not boot.