The image is rarely the problem. The match is. Use the official OpenWrt Firmware Selector to find your exact device and hardware revision, download a stable release image, and flash the factory or sysupgrade file that fits your starting point. Take a snapshot build only if you can read a boot log and accept that its packages may not be installable next month. That's the whole openwrt firmware selector workflow. The rest of this page is the detail that keeps it from going wrong.

What does the OpenWrt Firmware Selector actually do?

It's a search box on top of the official download server, with an optional build service behind it. You type a model, pick a release, and the OpenWrt Firmware Selector hands you the prebuilt images for that device. They're the same files that sit on the official download server. Nothing is compiled at this point.

The build service only runs when you change something. Open the panel for customizing installed packages and the first-boot script, edit the list, and request a build. The request goes to the Attended SysUpgrade server (ASU), which runs the OpenWrt ImageBuilder with your inputs and returns a fresh image.

What comes back is built from official repositories for one device, one release, and one package set. However, it can't add kernel features that weren't compiled into that release. If you need a kernel option the stock build leaves off, that's a source build. I cover that side in keeping a custom OpenWrt kernel config intact.

Identify the device before you search

Read the label on the bottom of the router before you type anything. Retail names leave things out. One model name can cover several hardware revisions with different chips and flash layouts, and their images won't boot on each other. The TL-WR841N family is the classic case: same box on the shelf, many revisions, several unrelated chipsets inside.

Collect these before you go near the selector:

• Vendor and exact model from the label, plus the hardware version line (often marked "Ver" or "H/W")
• Current firmware, stock or OpenWrt, and its version
• Flash size and partition layout
• The board name, if OpenWrt is already running

If the device already runs OpenWrt, run this first:

ubus call system board
cat /proc/mtd

The ubus call prints board_name, model, and the installed release. The board name is what sysupgrade checks against the image metadata, so it's the most trustworthy identifier you have. Meanwhile, /proc/mtd lists the flash partitions, and that tells you how the flash is carved up.

On stock firmware you have less to go on. Check the vendor's status page for the hardware version. Then compare the FCC ID on the label against the device's Table of Hardware entry.

Find the exact target, device, and image type

Search by model name, then slow down at the result list. The selector shows each device with its revision in the name, and you want the entry that matches your label exactly. A close match is a wrong match.

Each device page also names the target and subtarget, such as ath79/generic or ramips/mt7621. Write them down. You'll need them for ImageBuilder, for reading wiki pages, and for any forum post you end up writing.

Then pick the image type. The selector often offers several files, and they don't substitute for each other:

Some devices list only one of these. A few need a multi-step install that starts with the initramfs image. When the device page has install notes, follow them in order.

For a virtual machine, the x86/64 combined image is the one you want. My OpenWrt VM layout for Proxmox VLANs covers what comes after the download.

Choose a stable release unless you can debug snapshots

Default to the newest stable release the selector lists for your device. Releases get point updates with security and bug fixes. Their package repositories stay put for the life of the series, and kernel modules match the kernel you flashed. For a sense of the cadence, OpenWrt 25.12.6 shipped on 18 October 2026 as a point release in the 25.12 series. Check the version dropdown for what's current today, because any number on a blog goes stale.

Snapshots are the development branch, rebuilt continuously. Here is what happens when you run one:

• The kernel rolls forward. A kernel module you install next week may be built for a newer kernel than yours, and it will refuse to load.
• Packages don't stay put. The repository moves constantly, so a package you didn't bake in may not install against your image later.
• No web interface by default. Snapshots have historically shipped without LuCI, so you start with SSH unless you add it.
• Regressions are the point. Snapshots exist so breakage gets found.

So who should run them? People testing hardware support that hasn't reached a release yet. People chasing a fix that only exists in the development branch. Also anyone willing to read logread and file a bug. For everyone else, a snapshot on the main gateway means the whole household loses internet while you debug.

Build a minimal device-specific image

Bake in only what the device needs before it has working network access. That list is short: a driver for a USB modem, the protocol your ISP requires, LuCI on a snapshot. Everything else can go on after first boot, once you know the base image works.

Flash is the hard limit. Packages you bake in sit in the compressed read-only root, and the space left over becomes the writable overlay. Your config and later installs live in that overlay. Run df -h /overlay on a running device; if it's nearly full, config writes and upgrades fail in confusing ways.

There is one real argument for baking packages in. The read-only root compresses better than the overlay, so a package often takes less room inside the image than installed afterwards. Use that when space is tight. Don't treat it as permission to add everything.

The cargo-cult move is pasting a package list from a forum post wholesale. Conflicting packages, such as incompatible wpad variants, can fail the build with a dependency error or fight at boot. Big all-in-one bundles also push the image past the flash size, and the build request errors out. To drop a default package, delete it from the list in the selector. If you can't explain why a package is there, take it out.

Embed files and first-boot configuration deliberately

The selector gives you one hook here: a first-boot script under /etc/uci-defaults. OpenWrt runs scripts there during initial setup and normally removes them after successful completion. If a script fails, it can remain in place and run again on the next boot.

That means you should write it to be safe when repeated. Use uci set on named sections, which overwrites instead of duplicating. Avoid uci add unless you check first, and finish with uci commit.

uci set system.@system[0].hostname='lab-ap1'
uci set network.lan.ipaddr='192.168.50.1'
uci commit

mkdir -p /etc/dropbear
cat > /etc/dropbear/authorized_keys <<'EOF'
ssh-ed25519 AAAA... you@workstation
EOF
chmod 600 /etc/dropbear/authorized_keys

Two gotchas matter. First, the script ships inside the image in plain text, and the build server sees it too. A Wi-Fi key or root password in there is only as private as wherever that image file ends up. Second, settings in this script apply before you've logged in once. Opening SSH on WAN or enabling Wi-Fi with a weak key exposes the router from its first minute. Leave the default WAN firewall alone, since it already rejects inbound traffic.

If you need more than a script, such as a full tree of config files, that's ImageBuilder territory.

Download, verify, and flash

Verify before you flash

1. Note the SHA256 checksum the selector shows for your file.
2. Download the image and run sha256sum on it. A mismatch means you don't flash. Download again.
3. For release images, also check the signed checksum list in the target's download directory.
4. Read the filename out loud. It carries the release, target, subtarget, device, and image type, and every one of them should match your notes.
5. Know your recovery path before you start: failsafe mode, the vendor's TFTP recovery, or a serial console.

sha256sum openwrt-*-sysupgrade.bin
gpg --verify sha256sums.asc sha256sums
sha256sum -c sha256sums --ignore-missing

The gpg line confirms the checksum list came from the release signers. The last line checks every file you downloaded against that list. It ignores files you didn't download.

Pick the flashing path

From stock firmware, use the factory image through the vendor's upgrade page or recovery tool. Some vendors check the filename or region, so follow the device page. From OpenWrt via LuCI, use the backup and flash firmware page with the sysupgrade image. From the command line:

sysupgrade -b /tmp/backup.tar.gz # copy this off the box: /tmp is RAM
sysupgrade -T /tmp/openwrt-*-sysupgrade.bin
sysupgrade -v /tmp/openwrt-*-sysupgrade.bin

The -T flag tests the image without flashing, using the same board and metadata checks. If it reports a board name mismatch, stop and recheck your device. Don't reach for -F to force it. That check exists because someone already bricked that exact router.

What if the selector has no match for your router?

Don't force a near-match image. Instead, work out why the match is missing. It's usually one of these:

• Wrong revision. Another revision of your model is supported and yours isn't.
• OEM rebrand. ISP-branded and retailer-exclusive units often share hardware with a supported model under another name. Sometimes they share only the name.
• Dropped device. Devices with tiny flash or RAM fall out of current releases. They may still appear under older versions in the dropdown, but those get no security fixes.
• Snapshot only. Newly supported hardware lands in the development branch first.
• Missing driver. Some radios have no open driver, so the device stays unsupported or loses its Wi-Fi.

The OpenWrt Table of Hardware is where you settle this. Search by FCC ID or chipset as well as model name, then open the device page. Check the supported release, the flash layout, and the install method before downloading anything. If the table and the device page both say no, the real fix is a different router.

Legacy targets are not interchangeable with current platforms

Old wiki instructions often name targets that no longer exist. The ar71xx target was replaced by ath79, which describes hardware with device tree files. Board names changed in that move, and a sysupgrade from one to the other can't keep your settings.

Configs changed too. Many targets moved from the old swconfig switch setup to DSA, the kernel's Distributed Switch Architecture, so VLAN config written for one won't parse on the other. Some devices also got new partition layouts between releases. The image metadata carries a compatibility version, and sysupgrade refuses or demands a settings wipe (-n) when that version jumps.

So a guide that worked in its day can brick your router today. Trust the current supported-device record over any tutorial: the device page, its install notes, and the target the selector shows.

Use ImageBuilder for repeatable custom firmware

Move to ImageBuilder once you build the same image more than once. The same goes for flashing a fleet, embedding a whole tree of files, or wanting the build under version control. It's the same tool the build server runs, downloaded from your target's directory and run on an x86-64 Linux host.

make info | grep -i archer
make image PROFILE=tplink_archer-c7-v5 \
 PACKAGES="luci luci-proto-wireguard -ppp -ppp-mod-pppoe" \
 FILES=files/

make info lists the profiles. A minus prefix removes a default package. FILES=files/ copies a directory tree into the image root, so files/etc/config/network becomes /etc/config/network. Put the command, the package string, and the files/ tree in git. The same inputs against the same release give you the same image, which is what makes a build reproducible.

You can also point ImageBuilder at a local package feed for your own packages. The ceiling is the same as the selector: no kernel config changes. Things like eBPF need kernel options and a source build, which I cover in building OpenWrt with eBPF support.

Do not treat a custom firmware request as a package checklist

The forum post I'd skip writing is "please build me firmware with packages X, Y, and Z." The package list is rarely the real problem. Usually the router needs config, not packages, or it needs a kernel feature no package provides.

Before asking anyone for a build, collect the evidence:

• The boot log from dmesg, or from a serial console if it doesn't boot
• cat /proc/mtd and the output of ubus call system board
• The release you're on and the image you tried
• The real requirement, written as an outcome: "an access point with two SSIDs on separate VLANs," not a list of packages

That evidence sorts the request into four bins. Most turn out to be config problems. Some are missing packages the selector can add. A few need kernel options and a source build. The last bin is unsupported hardware, and no build fixes that.

If the selector's build itself fails, read the error it returns. Usually it's a package conflict or an image too big for the flash. Include that output in any bug report, along with the device, release, and package list.

Troubleshoot failed boots and missing features from evidence

Stop reflashing random images. Each reflash wipes the overlay and the evidence with it. Work through this order instead:

1. Serial console. Bootloader output tells you whether it found a valid image. A bad checksum or bad signature error means the wrong image or a bad write.
2. Kernel messages. If boot reaches the kernel and then fails to mount root, suspect the wrong image type or partition layout.
3. Failsafe mode. When the LED starts blinking during early boot, press the reset button. Faster blinking confirms failsafe mode. Then run mount_root and read logread and dmesg.
4. Missing features. Run logread -e hostapd for Wi-Fi trouble and dmesg | grep -i firmware for missing radio firmware. Then list installed packages with apk on newer releases or opkg on older ones.
5. Config drift. Run diff -r /rom/etc/config /etc/config to see exactly what changed from the defaults.

That last command is the one people forget. /rom holds the read-only original, so the diff shows every edit since flashing. Often that's one wrong line in one file. If you need to see what the router is doing on the wire after it boots, mapping OpenWrt traffic to devices with nlbwmon is the next step.

FAQ

Who builds the custom image, and can I trust it?

The OpenWrt project runs the build server, and it assembles your image from the same official package repositories as the stock downloads. It doesn't compile anything new. Treat your first-boot script as visible to that server, because it has to be.

Will packages I add after flashing survive the next upgrade?

No. A plain sysupgrade keeps your config files but replaces the overlay where installed packages live. Either bake them into the next image or use the attended sysupgrade client, owut on newer releases or auc on older ones. Both request a rebuild with your installed package list.

Can I go back to the vendor's firmware?

Usually, but the method depends on the device. Many routers have a TFTP or web recovery mode that accepts stock firmware. Some need a vendor image stripped of its header first. Check the device page before you try, and don't feed a vendor file to sysupgrade unless that page says it works.