Package feeds and China mirrors: keep apk and opkg separate

First: the difference between apk and opkg starts with the firmware release, not “which mirror is faster”. 25.12 uses apk; 24.10 uses opkg. Package format, feed paths and verification differ and are not interchangeable.

Outcome

Know whether the firmware uses apk or opkg, and where its feed files live.
Match release, target, architecture and the kmods kernel hash.
Know which part of the URL a China mirror replaces, and which paths must stay exact.
Understand why “after changing the mirror, packages will not install”, and how to recover.
Know why apk upgrade/opkg upgrade is not a firmware upgrade.

Identify the package manager and feeds

Router shellRead version, target and architecture

ubus call system board
cat /etc/openwrt_release
uname -m
cat /etc/apk/arch 2>/dev/null
opkg print-architecture 2>/dev/null

Key fields: release.version, release.target, DISTRIB_ARCH, release.revision. They must match the mirror path.

ExpectedYou can write the full release/target/arch combination.

Router shellInspect the current feed files

OpenWrt 25.12 (apk):

cat /etc/apk/repositories.d/distfeeds.list

OpenWrt 24.10 (opkg):

cat /etc/opkg/distfeeds.conf
cat /etc/opkg/customfeeds.conf

Back up before editing:

cp /etc/apk/repositories.d/distfeeds.list /etc/apk/repositories.d/distfeeds.list.bak.$(date +%F) 2>/dev/null || true
cp /etc/opkg/distfeeds.conf /etc/opkg/distfeeds.conf.bak.$(date +%F) 2>/dev/null || true

ExpectedYou know where each feed points and whether it is apk or opkg.

The apk layout in 25.12

OpenWrt 25.12 uses apk; indexes are .adb, packages are .apk. Typical feeds:

targets/<target>/packages/packages.adb: target-specific packages;
packages/<arch>/base/packages.adb: base;
packages/<arch>/luci/packages.adb: LuCI;
packages/<arch>/packages/packages.adb: general packages;
packages/<arch>/routing|telephony|video/packages.adb: category feeds;
targets/<target>/kmods/<kernel-hash>/packages.adb: kernel modules; the hash must match the running kernel.

Commands:

apk update
apk search <name>
apk add <name>
apk info -e <name>

Do not use opkg, and do not rename a 24.10 .ipk to .apk.

The opkg layout in 24.10

OpenWrt 24.10 uses opkg; indexes are Packages.gz, packages are .ipk:

opkg update
opkg list | grep <name>
opkg install <name>
opkg list-installed | grep <name>

Do not use apk, and do not feed a 25.12 .apk to opkg.

Rewriting to a China mirror

For the TUNA mirror, the root is:

https://mirrors.tuna.tsinghua.edu.cn/openwrt/

Replace only https://downloads.openwrt.org with that root and keep the entire path:

https://downloads.openwrt.org/releases/25.12.6/targets/x86/64/packages/packages.adb
→ https://mirrors.tuna.tsinghua.edu.cn/openwrt/releases/25.12.6/targets/x86/64/packages/packages.adb

Do not stop at .../openwrt/ or drop releases/25.12.6/targets/x86/64/...; an incomplete path returns 404.

Router shellVerify the mirror path before editing

curl -I https://mirrors.tuna.tsinghua.edu.cn/openwrt/releases/25.12.6/targets/x86/64/packages/packages.adb

Replace the URL with your release/target; for kmods, verify the kernel hash too. If the mirror lacks the path, do not force it.

Expectedcurl returns 200 and the path matches the current release/target.

Router shellUpdate indexes only, do not upgrade the system

apk update
# or
opkg update

Use apk search/opkg list to confirm the feed is readable, then install only what you need. Do not treat apk upgrade/opkg upgrade as a firmware upgrade; use sysupgrade/ASU/owut for firmware.

Expectedapk/opkg update succeeds without bulk-upgrading packages.

Common failures

404

Wrong release (25.12.6 vs 24.10.8);
Wrong target (x86/64, not an x86_64 directory);
Wrong architecture (x86_64, aarch64);
Mirror has not synced that path;
packages and targets directories mixed up.

Signature/verification failures

Corrupt index or a different release;
Wrong system time/certificates;
Another feed was mixed in;
Do not rely on --allow-untrusted; fix the feed/verification instead.

Dependency/ABI mismatch

kmods kernel hash does not match;
package built for another target/architecture;
official and ImmortalWrt/iStoreOS feeds mixed;
You need the same source, release and architecture, or a rebuild.

Command not found

25.12 has no opkg; 24.10 has no apk;
Do not install a package manager just to run a command; identify the firmware/source first.

Package installed but LuCI does not show it

Only the core package was installed; the luci-app-* package is missing;
Language pack missing;
Browser cache/refresh;
Package version does not match LuCI.

Recovery

# apk
cp /etc/apk/repositories.d/distfeeds.list.bak.YYYY-MM-DD /etc/apk/repositories.d/distfeeds.list
apk update

# opkg
cp /etc/opkg/distfeeds.conf.bak.YYYY-MM-DD /etc/opkg/distfeeds.conf
opkg update

If updates stop working after a mirror change, restore the official feed first, verify DNS/time/certificates, then try the mirror again. Do not hop between many mirrors.

E2 lab run (2026-10-20)

Environment: OpenWrt 25.12.6 x86 VM 200; apk; official feed and TUNA mirror.
Official apk update: OK: 11220 distinct packages available; apk search -x sqm-scripts found sqm-scripts-1.7.2-r1.
Switch to TUNA: apk update also 11220; apk add sqm-scripts installed 1.7.2-r1.
Restore official feed: apk update worked; final feed is back on downloads.openwrt.org.
Not tested: 24.10 opkg, signature errors, mixed/ABI mismatch, corrupt mirror index.
Recipe: tests/recipes/package-sources.md.

E2 status and sources

This is E2 partial: the 25.12 apk official/TUNA/install/restore path was tested; opkg and bad-feed branches remain documentation.
Mirror paths change with releases; rerun update/search on the target release/target/arch before publishing.
Do not mix official, ImmortalWrt or iStoreOS feeds; ABI/kernel/signatures can all mismatch.

Sources

Router.Homes

Independent OpenWrt notes. Every page states the firmware, device, package manager and way back.

Icons: Solar by 480 Design, CC BY 4.0