Skip to main content

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.

Prerequisites

Before you start upgrading, make sure to create a complete backup of your USB flash device. For more details, refer to Backing up your flash device.

Best practices before upgrading
  1. Make a backup of your flash drive and any important data.
  2. Read the Release Notes for the version you plan to install.
  3. Update all plugins to their latest versions.
  4. Optionally, stop the array before proceeding.
  5. Update Unraid OS using the Tools → Update OS page.
  6. Reboot your server to complete the upgrade.

Standard upgrade process​

Upgrading Unraid is done using the new Update OS tool with a user-friendly interface:

  1. In the WebGUI, click the top-right dropdown menu and select Check for Update or navigate to Tools → Update OS.
  2. Choose the Stable channel for stable releases, or the Next channel for betas and RCs.
  3. Click View Changelog to Start Update. The Changelog will appear for you to review before hitting Continue.
  4. Click Confirm and start update to apply the latest stable release.
  5. When prompted, reboot your server to complete the upgrade.
note

You may need to log into your Unraid account to access updates, especially for "Next" branch releases.

ZFS pool upgrade warnings

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 of ZFS.

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:

  1. Go to Settings → Docker and stop the Docker service.
  2. Check the box to delete the Docker image and click the delete button.
  3. Restart Docker to recreate the image.
  4. 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:

  1. Go to the VMs tab and edit each VM (make sure to enable Advanced View).
  2. Set the network bridge to br0 and click Apply.
  3. 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

For older VMs, you may need to update the VNC video driver:

  1. Edit the VM from the VMs tab (select Advanced View).
  2. Set the VNC Video Driver to QXL (recommended). Try Cirrus or vmvga if you have limited success with QXL.
  3. Click Apply to save the changes.
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:

  1. Type fs0:.
  2. Then type cd efi/boot.
  3. 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

To resolve this, edit the VM in the WebGUI and click Apply without making any changes. This action will update the machine type to the latest supported version.

Poor VM performance after upgrading - Click to expand/collapse

If your VM is slow after an upgrade, go to the VM settings (in Advanced View) and update the Machine type version to the latest revision (e.g., change from i440fx-2.5 to i440fx-2.7). Make sure not to change the prefix (for example, don't switch from i440fx to Q35).

Manual downgrade​

Manual downgrades 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 Backing up your flash device.

Only use these methods if you can't access the WebGUI:

  1. Download the Unraid version ZIP file from the Version History.
  2. Unzip the file on your computer.
  3. Access the flash share or connect the USB flash device to your computer.
  4. Create a previous directory if it doesn't already exist.
  5. Move all bz* and changes.txt files into the previous directory.
  6. Copy the new bz* and changes.txt files to the root of the flash drive.
  7. Reboot your server.
What happens during the downgrade process

When using the Downgrade OS tool (WebGUI), the tool will automatically handle the following:

  1. System validation: It checks that the downgrade is safe to perform.
  2. File backup: A backup of your current system files will be created.
  3. Version verification: The tool ensures that the files for the target version are valid and complete.
  4. File replacement: It replaces the current OS files with the files from the previous version.
  5. Configuration preservation: Your current settings will be maintained.
  6. System preparation: The system will be prepared for the previous version.
  7. Reboot scheduling: A reboot will be scheduled to finish the downgrade.

Post-downgrade verification​

After the downgrade is complete and your server has rebooted:

  1. Check the version: Verify that you're running the version of Unraid you expect.
  2. Test core functionality: Ensure that the array, Docker, and VM services are working properly.
  3. Verify plugins: Check that your installed plugins are compatible and functioning as expected.
  4. Test Docker containers: Start your Docker containers and confirm they are working correctly.
  5. Check VMs: If you have any virtual machines (VMs), make sure they start and operate properly. See VM setup for configuration guidance.
  6. Monitor system logs: Keep an eye on the system logs for any error messages. Use diagnostics tools to capture detailed system information.

Troubleshooting downgrade issues​

Downgrade option not available - Click to expand/collapse

If you don’t see an option to downgrade:

  • Check system history: Make sure you've previously upgraded from a compatible version.
  • Verify file integrity: Previous version files might be corrupted or missing.
  • Check compatibility: The earlier version may not be compatible with your current hardware.
  • Manual method: If needed, follow the manual downgrade methods outlined on this page.
Downgrade fails during process - Click to expand/collapse

If the downgrade process doesn't go as planned:

  1. Don’t panic: Your system should still work with the current version.
  2. Check logs: Take a look at the system logs to find specific error messages. Use diagnostics tools for comprehensive log analysis.
  3. Verify files: Ensure that all required files for the target version are available.
  4. Try the manual method: If the tool doesn't work, consider using the manual downgrade methods.
  5. Contact support: If problems continue, reach out to Unraid support with your diagnostics.
System won't boot after downgrade - Click to expand/collapse

If your system doesn’t boot after downgrading:

  1. Boot from USB: Use another computer to access your USB flash device. See boot troubleshooting for detailed recovery steps.
  2. Restore from backup: Copy your backup files back to the USB device.
  3. Check file integrity: Make sure all system files are present and not damaged.
  4. Try Safe Mode: Boot into Safe Mode for further troubleshooting.
  5. Manual recovery: If necessary, utilize the manual recovery methods.
Plugins or Docker containers not working - Click to expand/collapse

After downgrading, some plugins or containers may not function properly:

  • Update plugins: Look for plugin updates that work with the downgraded version. Check Community Applications for compatible versions.
  • Rebuild Docker: Delete and recreate your Docker image file. See Docker troubleshooting for detailed steps.
    • Check dependencies: Ensure that all necessary dependencies are available.
    • Plugin compatibility: Some plugins might not support earlier Unraid versions.
    • UI/WebGUI feature-dependent plugins: Plugins relying on newer WebGUI features may not operate correctly on older versions.
    • Theme plugins: Visual customization plugins may require updates or removal if they are incompatible.