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:

1

https://downloads.openwrt.org/

Then follow:

1

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:

1
2
3
4
5
6

mkdir -p ~/openwrt-imagebuilder
cd ~/openwrt-imagebuilder

tar --use-compress-program=unzstd \
  -xf openwrt-imagebuilder-*.tar.zst
cd openwrt-imagebuilder-*/

If unzstd is missing:

1
2

sudo apt update
sudo apt install -y zstd

View profiles and available packages

Run:

1

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:

1
2
3

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 -:

1
2
3

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:

1
2

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

For example:

1
2
3

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

Build with:

1
2
3
4

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

1
2
3
4
5
6

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

For verbose output:

1

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

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.

Official sources

• OpenWrt — Using the Image Builder
• OpenWrt — Build system usage
• OpenWrt downloads