Installing umbrelOS on Raspberry Pi

umbrelOS runs on the Raspberry Pi 5 and Raspberry Pi 4. We recommend the Pi 5 because it's much faster, but the Pi 4 works too. The same umbrelOS image works on both. See Running umbrelOS on your own hardware for what to expect.

For the best experience, install umbrelOS directly onto an NVMe or USB drive rather than a microSD card. Your apps and data are stored on the same drive umbrelOS runs from.

What you'll need

• Raspberry Pi 5 (recommended) or Raspberry Pi 4
• Official Raspberry Pi power supply
• Ethernet cable
• A drive to install umbrelOS on:
  • On a Pi 5, an NVMe drive with a compatible HAT, or a USB drive.
  • On a Pi 4, a USB drive. The Pi 4 has no NVMe slot, but an NVMe drive in a USB enclosure works.
• A computer to flash the image

Install umbrelOS

1. Download the latest umbrelOS image for Raspberry Pi.
2. Download and install Raspberry Pi Imager or Balena Etcher on your computer.
3. Connect your NVMe or USB drive to your computer (use a USB adapter for NVMe drives).
4. Open your flashing tool, select the umbrelOS image, select your drive, and flash it.
5. Safely eject the drive from your computer.

Boot your Raspberry Pi

1. Attach the flashed drive to your Raspberry Pi.
2. Remove any microSD cards. Otherwise the Pi may boot from the card instead.
3. Connect an ethernet cable to your Pi and your router.
4. Connect the official power supply to power on.
5. Wait a few minutes for the first boot to complete, then open http://umbrel.local in your browser.

See Connecting to your Umbrel if you need help accessing it.

Notes

• Bootloader updates. Older Pi 4 boards and early Pi 5 boards may need a bootloader update before they can boot umbrelOS from a USB or NVMe drive. See the Raspberry Pi documentation for instructions.
• NVMe compatibility varies by HAT, so check that your drive is compatible before purchasing.
• Always use the official power supply. Third-party supplies can cause stability issues.
• Storage Manager and FailSafe aren't available on Raspberry Pi. umbrelOS runs from the drive you flashed and stores your apps and data on it. Storage Manager still shows that drive's capacity and health.
• USB drives work as external storage. Any extra USB drive you plug in shows up under External storage in Files. You can use it for files, give apps access to its folders, or move supported apps onto it. See External storage.
• Machines run ARM versions of each operating system. On a Pi, Machines offers Ubuntu, Fedora, Debian, Alpine, Android, and Windows 11 for ARM.

Why not microSD?

You can run umbrelOS from a microSD card, but we don't recommend it. Your apps and data would then live on the card. microSD cards have a limited number of write cycles and degrade faster, leading to lower performance and reliability over time.

If you boot from a microSD card with a USB or NVMe drive connected, setup asks you to Select main storage:

• SD card keeps your apps and data on the SD card. The drive then shows up in Files as external storage.
• Choosing the drive shows steps to install umbrelOS directly onto it: shut down the Pi, use Raspberry Pi Imager on a computer to flash umbrelOS onto the drive, then remove the SD card and power on with the drive connected.

umbrelOS never formats a connected drive for you during setup. If you set up your Pi before umbrelOS 2.0 with a microSD card and a separate SSD for data, that setup keeps working after you update.