Upgrading packages may cause serious problems, including soft-bricking your device!

Blindly upgrading packages (manually or via script) can lead you into all sorts of trouble. Just because there is an updated version of a given package does not mean it should be installed or that it will function properly. Ensure yourself before doing an upgrade that it would be safe. Almost for sure avoid upgrading core packages.

There are two ways to manage and install packages in OpenWrt: with the LuCI web interface (System → Software), and via the command line interface (CLI). Both methods invoke the same apk or opkg command. The LuCI Upgrade... button performs the same apk upgrade or opkg upgrade command that is discussed in this article. The warnings apply to upgrading packages using LuCI (Upgrade...) and the CLI (apk upgrade or opkg upgrade).

Generally speaking, the use of apk upgrade or opkg upgrade is very highly discouraged. It should be avoided in almost all circumstances. In particular, bulk upgrading is very likely to result in major problems, but even upgrading individual packages may cause issues. It is also important to stress that this is distinctly different from the sysupgrade path for upgrading OpenWrt releases (major versions as well as maintenance upgrades). Using apk upgrade or opkg upgrade will not update the OpenWrt version. Only sysupgrade can do that, which includes using the Attended Sysupgrade in LuCI, and owut via the CLI. These are supported methods to upgrade your device safely, unlike apk upgrade or opkg upgrade.

Unlike the “big distros” of Linux, OpenWrt is optimized to run on systems with limited resources. This includes the apk or opkg package manager, which does not have built-in ABI (Application Binary Interface) compatibility and kernel version dependencies verification. Although sometimes there may be no issues, there is no guarantee and the upgrade can result in various types of incompatibilities that can range from minor to severe, and it may be very difficult to troubleshoot. In addition, the apk upgrade or opkg upgrade process will consume flash storage space. Since it does not (and cannot) overwrite the original (stored in ROM), it must store the upgraded packages in the r/w overlay.

In the vast majority of cases, any security patches of significant importance/risk will be rapidly released in an official stable maintenance release to be upgraded using the sysupgrade system. This is the recommended method for keeping up-to-date. As a reminder, this includes using the Attended Sysupgrade in LuCI, and owut via the CLI. These are supported methods to upgrade your device safely.

Those looking to be on the bleeding edge can consider using the snapshot releases, but should be mindful of the differences between stable and snapshot. Or, alternatively, build a custom image with the desired updated packages included in that image. The remaining users who still want to use apk upgrade or opkg upgrade should only do so with selected individual packages (do not bulk update, and do not blindly update) and they should be aware that problems may occur that could necessitate a complete reset-to-defaults to resolve.

If you're already having issues, or wish to “undo” the upgraded packages: create a backup (optional; can be restored after the reset is complete) and then perform a reset to defaults (firstboot).


If you do choose to upgrade packages using apk upgrade or opkg upgrade, you have been warned.

Don't complain on the forum, and be ready to deal with the consequences, troubleshooting, and resolution yourself.


See also