User Tools

Site Tools


Upgrading OpenWrt firmware via LuCI and CLI

  • Related pages:
    • Flash Layout: provides background on how OpenWrt uses device storage space

An OpenWrt upgrade will replace the entire current OpenWrt installation with a new version. This includes the Linux kernel, the SquashFS partition and the JFFS2 partition.

The common upgrade paths below will automatically preserve much of the OpenWrt OS configuration by saving and then restoring configuration files in specific common locations (including /etc/config). This will preserve things like OpenWrt network settings, WiFi settings, the device hostname, and so on.

The first part of the upgrade process is to prepare for the upgrade. This includes documenting programs and settings that will need to be re-installed or restored after the upgrade, locating and downloading the correct OpenWrt upgrade image for your hardware.

Next is the actual upgrade. There are two common upgrade paths to actually perform the upgrade. One uses the LuCI web interface “Flash new firmware image” command and one uses the command-line sysupgrade command. You can use either approach.

After the OS upgrade, there are usually some additional configuration steps required to re-install additional packages not part of the base OpenWrt install, to configure new OpenWrt functionality or to update configuration files to reflect new settings or updated packages. Please see the section below with more details.

Preparing for an OpenWrt upgrade

How the OpenWrt OS upgrade works

Both the LuCI and sysupgrade upgrade procedures work by saving specified configuration files, wiping the entire file system, installing the new version of OpenWrt and then restoring back the saved configuration files. This means that any parts of the file system that are not specifically saved will be lost.

In particular, any manually installed software packages you may have installed after the initial OpenWrt installation have to be reinstalled after an OpenWrt upgrade. That way everything will match, e.g. the updated Linux kernel and any installed kernel modules.

Any configuration files or data files placed in locations not specifically listed as being preserved below will also be lost in an OpenWrt upgrade. Be sure to check any files you have added or customized from a default OpenWrt install to back up these items before an upgrade.

See this howto about extroot procedure.

Identifying customizations

List user-installed packages identified in the opkg package database

From ''master'' in Early 2019

sysupgrade has been enhanced on the master branch to be able to capture a list of installed packages. These enhancements are not present in 18.06.02, but may be included in v19, when it is available. When available, the -k option will save a list. The relevant code is, as of February 1st, 2019:

# Format: pkg-name<TAB>{rom,overlay,unkown}
# rom is used for pkgs in /rom, even if updated later
find /usr/lib/opkg/info -name "*.control" \( \
        \( -exec test -f /rom/{} \; -exec echo {} rom \; \) -o \
        \( -exec test -f /overlay/upper/{} \; -exec echo {} overlay \; \) -o \
        \( -exec echo {} unknown \; \) \
        \) | sed -e 's,.*/,,;s/\.control /\t/' > ${INSTALLED_PACKAGES}

Either INSTALLED_PACKAGES must be defined, or the output can sent to the terminal by removing > ${INSTALLED_PACKAGES} or, for example, filtered for “overlay” (user-installed) by replacing > ${INSTALLED_PACKAGES} with | fgrep overlay

Other options

This script is from forum member gsenna and was originally posted in the forum discussion “Default packages attitude 12.09rc2 tplink 1043nd” at

# Save the script
cat << "EOF" > /tmp/
echo >&2 User-installed packages are the following:
sed -ne '/^Package:[[:blank:]]*/ {
/user installed/ {
}' /usr/lib/opkg/status
# Run the script
chmod +x /tmp/

Note that the script may list several packages that are part of the default OpenWrt install and will have their changed configuration files automatically backed up and restored. In addition, packages installed as dependences of other packages may show here. It is only important to note the names of packages that you directly installed manually. Any dependencies of these packages will automatically be reinstalled when the primary package is reinstalled.

An alternative script, that uses awk instead of sed/grep and is much shorter (provided by user valentijn):

# Save the script
cat << "EOF" > /tmp/listuserpackages.awk
#!/usr/bin/awk -f
/^Package:/{PKG= $2}
/^Status: .*user installed/{print PKG}
# Run the script
chmod +x /tmp/listuserpackages.awk
/tmp/listuserpackages.awk /usr/lib/opkg/status

This script will only output a list of user (and default) installed packages.

The alternative script below (by tboege), shows every package installed after the rom was build (flash_time), if no packages are depending on it. Packages, that are manually installed may be omitted, since one of the listed packages must depends of such a package, all manually installed packages will be installed, if the listet packages are installed:

cat << "EOF" > /tmp/listuserpackages.awk
#!/usr/bin/awk -f
    ARGV[ARGC++] = "/usr/lib/opkg/status"
    cmd="opkg info busybox | grep '^Installed-Time: '"
    cmd | getline FLASH_TIME
/^Package:/{PKG= $2}
    # Find all packages installed after FLASH_TIME
        cmd="opkg whatdepends " PKG " | wc -l"
        cmd | getline WHATDEPENDS
        # If nothing depends on the package, it is installed by user
        if ( WHATDEPENDS == 3 ) print PKG
# Run the script
chmod +x /tmp/listuserpackages.awk

List all packages associated with any user-modified file

This is an alternative to the script above. This command will list all packages related to any file in the whole file system that has changed from the default OpenWrt default version.

Note that the script may list several packages that are part of the default OpenWrt install and will have their changed configuration files automatically backed up and restored. In addition, packages installed as dependences of other packages may show here. It is only important to note the names of packages that you directly installed manually. Any dependencies of these packages will automatically be reinstalled when the primary package is reinstalled.

# OpenWrt 14.07 "Barrier Breaker" or earlier
find /overlay/ | while read FILE; do opkg search "${FILE#/overlay}"; done | sed -ne "s/\s.*//p" | sort -u
# OpenWrt 15.05 or later
find /overlay/upper/ | while read FILE; do opkg search "${FILE#/overlay/upper}"; done | sed -ne "s/\s.*//p" | sort -u

Configure your backup

Follow: Backup and restore

Based on the list of user-installed packages customize your backup configuration to save the files not included in the default list. Verify your backup configuration and ensure that all OpenWrt configurations and user data are going to be preserved.

OpenWrt on x86

:!: For x86 systems there is no “sysupgrade” image, just be sure to use the new firmware image has the same family of filesystem (if the current firmware uses squashfs then the new will use squashfs as well and if the current has ext the new will use ext filesystem. Note that an upgrade from ext2 [10.03.1] to ext4 [12.09] seems not working. Tested 10.03.1 squashfs to 12.09 squashfs, working ; 10.03.1 squashfs to 12.09 ext4 failed; 10.03.1 ext2 to 12.09 ext4 failed)

Downloading the OpenWrt upgrade image

Getting the right image

In most cases, platforms that support sysupgrade, have a downloadable image labelled “…-sysupgrade.bin”

WARNING: Double check you have the exact model number and in some cases country… If in any doubt about compatibility, read instructions on your device page thoroughly. If your are still unsure ask on the Forum.

For LuCI-based upgrades

  • Download the desired upgrade file to your PC using a web browser
  • Proceed to the LuCI upgrade procedure, below

For sysupgrade-based upgrades

  • Download the desired upgrade file to the local /tmp RAM drive on your OpenWrt system. The /tmp directory is stored in RAM (using tmpfs), not in the permanent flash storage.
# example downloading the OpenWrt 15.05 upgrade image for a TP-LINK TL-WR1043ND ver. 1.x router
cd /tmp
# check the integrity of the image file
# via md5sums
# via sha256sums
# the desired result is that the downloaded firmware filename is listed with "OK" afterwards
# via md5sums
md5sum -c md5sums 2> /dev/null | grep OK
# via sha256sums
sha256sum -c sha256sums 2> /dev/null | grep OK
  • Proceed to the “Ensure desired configuration files will be saved” section, above
Troubleshooting: /tmp is too small to hold the downloaded file

If your device's /tmp filesystem is not large enough to store the OpenWrt upgrade image, this section provides tips to temporarily free up RAM.

First check memory usage with the free or top or cat /proc/meminfo commands; proceed if you have as much free RAM as the image is in size plus an some additional MiB of free memory.

root@openwrt:/$ free total used free shared buffers Mem: 29540 18124 11416 0 1248 -/+ buffers: 16876 12664 Swap: 0 0 0

In this example there are precisely 11416 KiB of RAM unused. All the rest 32768 - 11416 = 21352 KiB are used somehow and a portion of it can and will be made available by the kernel, if it be needed, the problem is, we do not know how much exactly that is. Make sure enough is available. Free space in /tmp also counts towards free memory. Therefore with:

root@openwrt:/$ free Mem: 13388 12636 752 0 1292 Swap: 0 0 0 Total: 13388 12636 752
root@openwrt:/$ df Filesystem 1K-blocks Used Available Use% Mounted on /dev/root 2304 2304 0 100% /rom tmpfs 6696 60 6636 1% /tmp tmpfs 512 0 512 0% /dev /dev/mtdblock3 576 288 288 50% /overlay mini_fo:/overlay 2304 2304 0 100% /

One has actually 752+6636 KiB of free memory available.

  • quickest and safest way to free up, some RAM is to delete the opkg packages file:
rm -r /tmp/opkg-lists/
  • drop caches:
sync && echo 3 > /proc/sys/vm/drop_caches
  • prevent wireless drivers to be loaded at next boot and then reboot:
rm /etc/modules.d/*80211*
rm /etc/modules.d/*ath9k*
rm /etc/modules.d/b43*

The wireless drivers, usually take up quite some amount of RAM and are not required (unless you are connected via wireless of course ;-)), so an easy way to free up some RAM is to delete the symlinks in etc/modules.d so these are not loaded into memory at the next reboot.

OpenWrt Upgrade procedure

Web interface

  1. Navigate to LuCI → System → Backup / Flash Firmware → Actions: Flash new firmware image.
  2. Click Choose File button to select firmware image.
  3. Click Flash image… to upload firmware image.
  4. Verify firmware image checksum and proceed.
  5. Wait until the router comes back online.

Command-line interface

OpenWrt provides sysupgrade utility for firmware upgrade procedure.

Verify firmware image checksum. Verify the router has enough free RAM. Upload the firmware from local PC. Flash the firmware.

# Check the free RAM 
# Upload firmware
scp firmware_image.bin root@openwrt.lan:/tmp
# Flash firmware
sysupgrade -v /tmp/firmware_image.bin

If sysupgrade is not available.

# Flash firmware
mtd -r write /tmp/firmware_image.bin firmware

If free RAM is limited.

# Upload and flash firmware
cat firmware_image.bin | ssh root@openwrt.lan mtd write - firmware
  • The sysupgrade verbose-option should give some output similar to this. The list of configuration files saved will change depending on what packages you have installed and which files you have configured to be saved, as per above.
Saving config files...
killall: watchdog: no process killed
Sending TERM to remaining processes ... ubusd askfirst logd logread netifd odhcpd snmpd uhttpd ntpd dnsmasq
Sending KILL to remaining processes ... askfirst
Switching to ramdisk...
Performing system upgrade...
Unlocking firmware ...

Writing from <stdin> to firmware ...  [w]
Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...TRX header not found
Error fixing up TRX header
Upgrade completed
Rebooting system...

Note: The “TRX header not found” and “Error fixing up TRX header” errors are not a problem as per OpenWrt developer jow's post at

  • Wait until the router comes back online
  • After the automatic reboot, the system should come up the same configuration settings as before: the same network IP addresses, same SSH password, etc.
  • Proceed to the “Additional configuration after an OpenWrt upgrade” section, below


  • In case it does not, try a cold reset (= interrupt the electrical current to the device, wait a couple of seconds and then connect it again).
For unknown reasons such a cold reset has often been reported to be necessary after a sysupgrade. This is very very bad in case you performed this remotely!


Verify the new OS version

  • In LuCI, go to Status > Overview to verify you are running the new OpenWrt release
  • In SSH, the login banner has the release information

Check for any upgradable packages

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. Inform yourself before doing any upgrades to determine if it is safe to upgrade. Avoid upgrading core packages,

There are two ways to manage/install packages in OpenWrt: With the LuCI web interface Software menu (System > Software), and via the command line interface (CLI). Both methods invoke the same CLI opkg executable, and as of OpenWrt 19.07.0, the LuCI interface now has an 'Updates' tab with a listing of packages that have available upgrades. The LuCI Upgrade… button performs the same opkg upgrade command that is discussed in this article. The same warnings apply to upgrading packages using LuCI and the CLI.

Generally speaking, the use of 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). opkg upgrade will not update the OpenWrt version, only sysupgrade can do that – the two are not equivalent.

Unlike the 'big distros' of Linux, OpenWrt is optimized to run on systems with limited resources. This includes the 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 ugprade 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 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.

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 opkg upgrade should only do so with selected individual packages (do not bulk update, 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 chose to upgrade packages, especially with a script: You have been warned. Don't complain on the forum and be ready to deal with the consequences, troubleshooting, and resolution yourself.

After the initial update, it is good to check for any updated packages released after the base OS firmware image was built.

  • List any available upgradable packages
opkg update
opkg list-upgradable
  • Upgrade any packages listed (if any were listed) – more than one package can be included
    • Note: on a device with only 4MB of NVRAM, these updates may not fit – check free space on / first with “df -h /” and ensure there is at least 600KB or so free
opkg list-upgradable | sed -e "s/\s.*//" | while read PKG_NAME; do opkg upgrade "${PKG_NAME}"; done
  • Verify no more packages can be upgraded; the command should display no output now
opkg list-upgradable

Reinstall user-installed packages

After a successful upgrade, you will need to reinstall all previously installed packages. You made a list of these above. Package configuration files should have been preserved due to steps above, but not the actual packages themselves.

  • Restore pre-upgrade packages “automagically”

If you have used “sysupgrade -k” you should be able to run the following code to restore all packages (credits to rnio)

opkg update && opkg list-installed | cut -f 1 -d ' ' | sort -u > /tmp/currentpkg && cat /etc/backup/installed_packages.txt | cut -f 1 | sort -u > /tmp/oldpkg && grep -v -F -x -f /tmp/currentpkg /tmp/oldpkg > /tmp/inst && opkg install $(cat /tmp/inst | sort -u) && rm /tmp/currentpkg /tmp/oldpkg /tmp/inst
  • Install packages manually
opkg update
opkg install snmpd-static

Configure user-installed packages

The new package installations will have installed new, default versions of package configuration files. As your existing configuration files were already in place, opkg would have displayed a warning about this and saved the new configuration file versions under …-opkg filenames.

The new package-provided configuration files should be compared with your older customized files to merge in any new options or changes of syntax in these files.

The diffutils program is helpful for this.

For example:

opkg install diffutils                          # install diffutils
find /etc -name *-opkg                          # locate all -opkg files
diff /etc/config/snmpd /etc/config/snmpd-opkg   # compare /etc/config/ snmpd(existing) vs snmpd-opkg(fresh)
vi /etc/config/snmpd; rm /etc/config/snmpd-opkg # merge needed changes to the active version
mv /etc/config/snmpd-opkg /etc/config/snmpd     # or use fresh package maintainer version
service snmpd restart                           # apply new configuration

Legacy Notes

Information herein that pertains to 17 or older releases and/or no longer generally advised.

Legacy: LuCI flash_keep section of /etc/config/luci

LuCI has a separate set of settings for configuration files to be preserved, however it appears to be obsolete since OpenWrt 14.07 and should be ignored.

uci show luci.flash_keep
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
docs/guide-user/installation/generic.sysupgrade.txt · Last modified: 2020/01/11 10:06 by oilervoss