OpenWrt 25.12+: Use apk Instead of opkg Without Bricking the Router

From OpenWrt 25.12, the package manager is apk version 3; opkg has ended development and is no longer the primary choice on the new release. This apk is Alpine Package Keeper, not an Android APK.¹

Start with the release check: this guide targets OpenWrt 25.12 and newer. If the firmware still uses opkg, follow that release's documentation and do not mix package managers or repositories.

1
2

cat /etc/openwrt_release
apk --version

1. Basic commands

The OpenWrt documentation lists these core commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

apk update
apk add <package>
apk add <package>*
apk add --allow-untrusted ./<package>.apk
apk add --allow-untrusted ./*.apk
apk del <package>
apk del <package>*
apk list -I
apk list -a [<package>*]
apk search [<needle>*]

apk update refreshes the local package database. apk add installs packages, and * is a mask for matching multiple names. --allow-untrusted is intended for packages built locally or downloaded from an external feed, so I use it only after checking the package source and trust model. apk del removes packages, apk list -I lists installed packages, apk list -a lists available packages, and apk search searches by a string.

Update the database and install several packages in one operation:

1

apk -U add package1 package2 package3

2. Repository feeds

Repository databases are listed in files below /etc/apk/repositories.d/. Inspect the active feed:

1

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

The source shows this x86_64 example for the 25.12 release. It illustrates the layout; do not copy x86_64 feeds to another target:

1
2
3
4
5
6
7
8

https://downloads.openwrt.org/releases/25.12/targets/x86/64/packages/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/base/packages.adb
https://downloads.openwrt.org/releases/25.12/targets/x86/64/kmods/6.12.60-1-41eae5d636a323424ce95c71d55e15f0/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/luci/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/packages/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/routing/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/telephony/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/video/packages.adb

Keep custom feeds in their own file so they can survive upgrades:

1

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

The source's sample is:

1
2
3

# add your custom package feeds here
# http://www.example.com/path/to/files/packages.adb
https://dev.melmac.net/apk/packages.adb

Add a feed only when its target, release, and ABI match the firmware; --allow-untrusted cannot fix a wrong kernel or architecture.

3. Package upgrades: the easiest way to brick a router

Do not blindly mass-update with:

1

apk upgrade

The documentation warns that packages such as hostapd-*, wpad-*, ucode-mod-*, and various libraries may have conflicts or incomplete dependencies. A blind upgrade can misconfigure the router and eventually prevent booting or remove Wi-Fi.¹

The safe way to update the complete package set is a sysupgrade to a firmware image with a coherent package set. Use an ASU client such as LuCI Attended Sysupgrade, owut, or Firmware Selector, or build with Image Builder or the full toolchain on a Linux host. Back up first.

If I deliberately update packages after understanding the risks, the source's command is:

1

apk upgrade

This is a conditional branch, not a recommendation for routine upgrades. Have a backup, a console or recovery path, and a verified target/repository combination before running it.

4. Command groups left for reference

The source contains headings for Invocation, Package manipulation, Informational commands, Options, Configuration, Adjust repositories, and Change architectures, but the published page does not provide additional command examples in those sections. I do not invent syntax for an empty subsection; use apk --help and documentation for the exact apk v3 build when needed.

The source does provide proxy guidance. apk reads http_proxy and https_proxy; run a one-off operation through a proxy with:

1

https_proxy=http://yourproxyserver:3128/ apk upgrade

Replace the example host and port with the real proxy, and do not put proxy credentials into shell history or public Markdown.

5. Troubleshooting and limits

apk v3 differences

OpenWrt 25.12 uses apk v3. Alpine Linux also uses v3, but Wolfi, Apko, Melange, and Chainguard may still use apk v2; do not copy an apk v2 man page into an OpenWrt v3 workflow.

Out of space

The source has an Out of space section but no complete command sequence. Do not delete system files or switch repositories at random. Inspect the filesystem and installed packages, then use extroot or the release-appropriate expand_root procedure when supported.

Non-standard installation destinations

The source also has a Non-standard installation destinations section without a complete procedure. I do not treat apk add as a safe way to relocate the entire root filesystem; inspect the target and init-system documentation first.

Known issues

The source notes that:

1

apk adbdump

may produce non-standard YAML in edge cases. Report that behavior through apk's issue tracker instead of feeding the output into an automation script.

6. Pre-install checklist

1. Check cat /etc/openwrt_release and confirm 25.12+.
2. Inspect /etc/apk/repositories.d/distfeeds.list and confirm target/architecture.
3. Run apk update and resolve repository errors before installing.
4. For external packages, check the signature, target, and reason for using --allow-untrusted.
5. Do not use apk upgrade as a substitute for a firmware sysupgrade.
6. Back up before touching wpad, hostapd, kernel modules, or core libraries.

Conclusion

apk gives OpenWrt 25.12 a new package manager, but it does not remove the embedded-firmware constraints: ABI, kernel modules, flash space, and a coherent image still matter more than running one upgrade command. I use apk update and targeted apk add for an explicit purpose, while a complete system update goes through a coherent sysupgrade.

Sources