How to Build OpenWrt from Source for Beginners

This article is based on the official OpenWrt documentation, with additional explanations for beginners. Never flash an image built for one model onto another model without checking the target, profile, and recovery method.

When should you build OpenWrt from source?

A source build is useful when you want to customize the kernel, packages, patches, default configuration, or firmware for a specific target. If you only need to add packages to an existing image, ImageBuilder is usually faster and simpler.

OpenWrt's build system creates the cross-compilation toolchain, kernel, root filesystem, and image components for the selected target.

Prepare a Linux build environment

Use a 64-bit Linux computer with enough disk space and RAM. On Debian or Ubuntu, install the basic build tools:

1
2
3
4

sudo apt update
sudo apt install -y build-essential clang flex bison g++ gawk gcc-multilib \
  gettext git libncurses-dev libssl-dev python3 python3-distutils \
  python3-setuptools rsync unzip zlib1g-dev file wget

Package names differ between distributions. If a package is unavailable, find the equivalent for your distribution rather than skipping the dependency.

Download the OpenWrt source

The OpenWrt documentation recommends using the official repository or a project mirror:

1
2

git clone https://github.com/openwrt/openwrt.git
cd openwrt

Use a dedicated directory such as ~/src/openwrt instead of a system directory so that multiple branches and build caches are easier to manage.

Select a branch or tag

Use main for the newest development changes. For a router used in production, select a stable branch or tag supported by the device and read the release notes first.

1
2
3

git fetch --all --tags
git branch -a
git checkout <suitable-branch-or-tag>

Replace the placeholder with a version tested for your router. Do not copy the command and flash the result without checking the target.

Update feeds

Feeds provide packages used during the build:

1
2

./scripts/feeds update -a
./scripts/feeds install -a

If a feed fails, read the URL and error in the terminal before trying again. Do not delete .config blindly, because that can remove the selected target.

Select the target with menuconfig

Open the configuration interface:

1

make menuconfig

Important options include:

• Target System: SoC or platform family.
• Subtarget: hardware branch within the target.
• Target Profile: exact router model.
• LuCI: web interface, if needed.
• Base system and Network: core packages.

Compare the router with the supported-device list and image profile. A wrong target can produce an image that does not boot or cannot be flashed.

Save the configuration and generate defaults if needed:

1

make defconfig

Back up .config:

1

cp .config configs/my-router.config

Download package sources before compiling

Detect download problems early:

1

make download -j$(nproc)

If a mirror is slow or fails, check the URL, proxy, DNS, and network before starting the compile.

Build the firmware

Normal build:

1

make -j$(nproc)

If the computer has limited RAM, reduce parallelism:

1

make -j2

For detailed output from one failing step:

1

make V=s -j1

Firmware and packages are normally placed under bin/targets/. The exact filenames depend on the target, subtarget, profile, and .config choices.

Check the image before flashing

1. Verify the target and profile in bin/targets/.
2. Check the checksum when available.
3. Back up the original firmware and configuration.
4. Prepare UART, TFTP, or web-recovery access. For UART boot logs, a USB-to-TTL adapter such as this FT232 adapter can be used; connect only GND, RX, and TX at the correct voltage.
5. Ensure stable power.
6. Read the flashing guide for the exact router model.

Tool selection summary

Official sources

• OpenWrt — Build system setup
• OpenWrt — Build system usage
• OpenWrt — Build system essentials
• OpenWrt source repository