Upgrading Unraid
Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options.
Before you start upgrading, make sure to create a complete backup of your USB flash device. For more details, refer to Changing your flash device.
- Make a backup of your flash drive and any important data.
- Read the Release Notes for the version you plan to install.
- Update all plugins to their latest versions.
- Optionally, stop the array before proceeding.
- Update Unraid OS using the Tools → Update OS page.
- Reboot your server to complete the upgrade.
Standard upgrade process
- Unraid 7.x and later
- Unraid 6.11 to 6.12
Upgrading Unraid is done using the new Update OS tool with a user-friendly interface:
- In the WebGUI, click the top-right dropdown menu and select Check for Update or navigate to Tools → Update OS.
- Choose the Stable channel for stable releases, or the Next channel for betas and RCs.
- Click View Changelog to Start Update. The Changelog will appear for you to review before hitting Continue.
- Click Confirm and start update to apply the latest stable release.
- When prompted, reboot your server to complete the upgrade.
You may need to log into your Unraid account to access updates, especially for "Next" branch releases.
For Unraid versions 6.11 and 6.12, follow this traditional update method:
- In the WebGUI, go to Tools → Update OS.
- Click Check for Updates.
- If a new release is available, click Update.
- Reboot your server when prompted.
When upgrading to Unraid 7.x, you may see warnings about ZFS pool feature upgrades during boot or in the WebGUI. These warnings are not a sign of a problem; they simply indicate that your ZFS pool is using features from an older version
Upgrading your pool isn't urgent, but if you do decide to upgrade, keep in mind that it may not work with previous versions of Unraid. This means you may not be able to revert to a previous Unraid version after making the upgrade.
As always, remember to back up your data before upgrading your ZFS pools
Troubleshooting upgrade issues
If you run into problems after upgrading, check the relevant section below for assistance.
Array or docker containers are slow to start after upgrade - Click to expand/collapse
A one-time migration may be necessary for Docker containers after certain upgrades. This process can take time, especially if you have many images. Be patient during this process; performance should normalize after the initial start.
Docker containers are not working correctly after upgrade - Click to expand/collapse
If you encounter errors like "layers from manifest don't match image configuration," you may need to rebuild your Docker image file. Here’s how:
- Go to Settings → Docker and stop the Docker service.
- Check the box to delete the Docker image and click the delete button.
- Restart Docker to recreate the image.
- Navigate to the Apps tab, Previous Apps and check off what you wish to reinstall and click "Install xx Applications".
VMs show "cannot get interface MTU" or network errors - Click to expand/collapse
If you've used a custom bridge name for VM networking, update all VMs to use the default br0
bridge by following these steps:
- Go to the VMs tab and edit each VM (make sure to enable Advanced View).
- Set the network bridge to
br0
and click Apply. - Navigate to Settings → VM Manager (in Advanced View) and set the default bridge to
br0
.
VNC access to VMs is not working or is slow - Click to expand/collapse
VM will not boot (EFI shell appears) - Click to expand/collapse
If you have OVMF-based VMs created in older Unraid versions, you might encounter an EFI shell. You can boot the VM by entering the following commands:
- Type
fs0:
. - Then type
cd efi/boot
. - Finally, type
bootx64.efi
.
If fs0:
doesn't work, you can try fs1:
instead. If you continue to have issues, please visit the Unraid forums for assistance.
Trying to start my VM gives an "Invalid machine type" error - Click to expand/collapse
Poor VM performance after upgrading - Click to expand/collapse
Manual upgrade or downgrade
Manual upgrades are infrequently necessary but may be needed if you can't access the WebGUI or need to revert to a prior version. Before proceeding, it's important to back up your USB flash device, details of which you can find in Changing your flash device.
Downgrade using the OS tool (if WebGUI is accessible)
If you can reach the WebGUI:
- Log in to the WebGUI.
- Navigate to Tools → Downgrade OS.
- Your previous version will be listed as the available downgrade option.
- Click Downgrade and follow the prompts.
- Reboot your server when prompted.
Keep in mind that downgrading can lead to compatibility issues with plugins or Docker containers. Always back up your USB flash device and any important data beforehand.
Manual methods (if WebGUI is inaccessible)
Only use these methods if you can't access the WebGUI:
- Simplest method
- Command line method
- Download the Unraid version ZIP file from the Version History.
- Unzip the file on your computer.
- Access the
flash
share or connect the USB flash device to your computer. - Create a
previous
directory if it doesn't already exist. - Move all
bz*
andchanges.txt
files into theprevious
directory. - Copy the new
bz*
andchanges.txt
files to the root of the flash drive. - Safely eject the drive and reboot your system.
This method should only be used if you are comfortable with the Linux command line, as mistakes might make your system unbootable.
-
Copy the URL of the desired Unraid version ZIP file from the Version History.
-
Log in via SSH or console.
-
Execute the following commands one at a time (replace
<URL>
with the copied link):cd /tmp
rm -f unraid.zip
rm -rf unraid_install
wget -O unraid.zip <URL>
[[ -s unraid.zip ]] && echo "OK to continue" || echo "STOP: the file was not downloaded"
unzip -d unraid_install unraid.zip
[[ -s unraid_install/bzroot ]] && echo "OK to continue" || echo "STOP: the file was not extracted properly"
[[ ! -d /boot/previous ]] && mkdir /boot/previous
mv /boot/bz* /boot/previous
mv /boot/changes.txt /boot/previous
cp unraid_install/bz* /boot
cp unraid_install/changes.txt /boot
sync -f /boot
sleep 5
reboot