How to update from umbrelOS 0.5 to the latest umbrelOS 1.x on Linux devices

Announcements
1

umbrelOS 1.x is finally here for users running umbrelOS 0.5 on devices using Ubuntu and Debian!

If you prefer a fresh installation of the latest umbrelOS release and do not want to migrate your existing data, follow the instructions here.

A little background

You may remember installing umbrelOS 0.5 using the command curl -L https://umbrel.sh | bash on your device. This method layered umbrelOS on top of your underlying operating system (i.e. Ubuntu or Debian) using a series of scripts and system services.

umbrelOS 1.0 brings a complete architectural overhaul, and it’s been rebuilt as a standalone operating system that installs directly onto your device’s internal storage. This change is crucial because umbrelOS now handles low-level operations like disk partitioning and file-system management. And by operating in a fully controlled environment, it increases the security, performance, and stability of the entire system.

We could not deploy umbrelOS 1.0 as an over-the-air update for devices running Ubuntu/Debian because it involves replacing the entire underlying operating system.That said, with the introduction of umbrelOS 1.0, future updates will be delivered over-the-air.

umbrelOS 1.0 implements a robust A/B partitioning scheme that enables OTA updates with rollback capabilities, allowing us to update the entire OS image, including drivers and the Linux kernel. This ensures we can deliver critical security updates reliably and safely — a limitation we faced previously.

As a result of the new OTA update architecture, any modifications made to the umbrelOS system (host OS) manually via ssh/terminal will not be saved across software updates. If you’re looking to run custom software in a Linux environment, consider using the Portainer app available in the Umbrel App Store.

How to update from umbrelOS 0.5 to the latest umbrelOS 1.x

Note: umbrelOS 1.x is compatible only with x86 systems (devices powered by 64-bit Intel or AMD CPUs). ARM-based devices, other than Raspberry Pi 4 and Pi 5, are not supported.

View instructions to update on a:

How to update from umbrelOS 0.5 on a Linux device

Prepare for migration

You’ll need an external USB drive of sufficient size to export your existing umbrelOS data and apps. You can check your current umbrelOS storage usage in the Settings to ensure that your external drive can accommodate your data.

Step 1: Export your umbrelOS 0.5 data and apps to the external drive

  • Connect the external drive to your device (that is running umbrelOS 0.5.x) via a USB port.

  • Open Terminal on your device (through SSH or direct access), navigate to your Umbrel installation directory, and run:
    curl -sL https://export.umbrel.sh | sudo bash

    curl -sL https://export.umbrel.sh | sudo bash
    curl -sL https://export.umbrel.sh | sudo bash2894×1918 655 KB

  • Follow the on-screen instructions. You will also be asked to confirm the location of your external drive — make sure to enter the correct path to select the appropriate drive. Here is a quick video demonstrating the entire process:

  • Once you see the output “Done! Your Umbrel data has been exported to your external USB storage device”, you can shutdown your device.

    2894×1918 952 KB

  • Important: Make sure to disconnect the external drive from your device after the shutdown.

Step 2: Install the latest umbrelOS on your device’s internal storage

Prepare a bootable USB stick

  • Download the latest umbrelOS 1.x USB installer umbrelos-amd64-usb-installer.iso.xz on your computer.
  • Download and install Balena Etcher on your computer.
  • Plug a USB stick (at least 4GB) into your computer. Ensure that it doesn’t contain any important data as it will be formatted.
  • Use Balena Etcher to flash the umbrelos-amd64-usb-installer.iso.xz file to the USB stick.
    1824×1184 346 KB

Boot from USB Stick

  • Remove the USB stick from your computer, and insert it into your device.
  • Connect a display and keyboard to your device (for desktops or NUCs/Mini PCs).
  • Plug an Ethernet cable into your device and connect it to your internet router.
  • Turn on the device. It should automatically boot from the USB stick.

Note: If it doesn’t automatically boot from the USB stick, you might need to change the boot priority order in your device’s BIOS settings.

Install umbrelOS on internal storage

  • After the system boots up, it will present you with the following screen:
    umbrelOS x86 USB Installer
    umbrelOS x86 USB Installer1942×1302 479 KB
  • Identify the correct internal storage device where you intend to install umbrelOS, and note its corresponding number. For instance, in the above screenshot, if we want to install it on the ‘ATA’ drive, which has a capacity of ‘238.5G’, we’d type ‘1’ (without the quotes) and press Enter.

Finalize installation

  • After the flashing process is complete, turn off the device by pressing any key.
  • Remove the USB stick, keyboard, and display.

Step 3: Boot up your device, and auto-import your data from external drive

  • Ensure that the Ethernet cable is connected between your device and the router.

  • Connect the external drive containing the exported umbrelOS 0.5.x data to your device via USB.

  • Important: Double-check that the external drive is connected via USB to the device. Once confirmed, turn on the device.

  • The first boot will take about 5 minutes. After that, umbrelOS will automatically detect the connected external drive and auto-import all your data. You can visit http://umbrel.local on any device connected to the same network to monitor the data import (migration) process.

    umbrelOS 1.1 Migration Assistant
    umbrelOS 1.1 Migration Assistant3248×2112 1.95 MB

If you cannot access http://umbrel.local, and you are using a Windows computer, try accessing http://umbrel. Alternatively, use your router’s admin dashboard or a network scanning tool like ‘Fing’ to find your device’s IP address on your local network. If needed, you can connect a display and a keyboard to your device, log in, and run hostname -I to find its IP address. Then, enter this IP address directly into a web browser to access umbrelOS.

If you are prompted to create a new account instead of seeing the login screen, this would indicate that your data wasn’t imported. Do not create a new user account, and instead restart your device with the external USB drive connected to try importing your data again.

How to update from umbrelOS 0.5 on a Linux VM

  1. Stop Umbrel inside the VM by running sudo ./scripts/stop from the Umbrel installation directory.

  2. Create a tarball of your entire Umbrel data:
    sudo tar -cvf umbrel-data.tar -C /path/to/umbrel/installation .

  3. Copy the umbrel-data.tar file out of the VM onto your host OS (or to an external drive).

  4. Download and extract umbrelos-amd64-usb-installer.iso.xz on your computer.

  5. Create a new VM with a fresh virtual hard drive. Attach umbrelos-amd64-usb-installer.iso to the VM, and boot from it.

  6. Follow the on-screen instructions to install umbrelOS on your VMs internal storage.

  7. Shutdown the VM and remove the umbrelos-amd64-usb-installer.iso image.

  8. Copy umbrel-data.tar from your host OS into the new VM.

  9. Create the directory /home/umbrel/umbrel/import inside your VM and extract umbrel-data.tar into it by running:
    mkdir /home/umbrel/umbrel/import && tar -xvf umbrel-data.tar -C /home/umbrel/umbrel/import

  10. Restart the new VM. umbrelOS will now automatically detect and import all your data.

  11. After the restart, open http://umbrel.local, and you should be greeted with the login page (not a signup page). You can now login with your umbrelOS 0.5 password.

  12. After login, ensure all your data and applications are correctly imported and functional. Once confirmed, you can safely delete the old VM.

How to update from umbrelOS 0.5 on a Linux VPS

Updating from umbrelOS 0.5.x to 1.x on a Virtual Private Server (VPS) isn’t supported at the moment.

4 Likes