Installing umbrelOS on Raspberry Pi

umbrelOS runs on the Raspberry Pi 5 and Raspberry Pi 4. We recommend the Pi 5: it's much faster, more reliable for long-term use, and it works well with USB drives, which can make a Pi 4 crash. It also usually starts umbrelOS without any extra steps. The Pi 4 is fine for tinkering, or if you already have one, but many Pi 4 boards need a bootloader update first. The same umbrelOS image works on both. See Running umbrelOS on your own hardware for what to expect.

We recommend running umbrelOS from a microSD card, 32 GB or bigger. Your apps and files are stored on the card too, and any USB drive you plug in later works as extra storage. Running umbrelOS from a USB drive doesn't work on every Pi yet; see Running umbrelOS from a USB drive for why.

What you'll need

• Raspberry Pi 5 (recommended) or Raspberry Pi 4
• A microSD card, 32 GB or bigger. A good-quality card from a known brand is faster and lasts longer, and a bigger card leaves more room for your apps and files.
• Official Raspberry Pi power supply
• Ethernet cable
• A computer with a microSD card slot or card reader, to flash the image

On a Pi 4, update the bootloader first

umbrelOS 2.0 needs a recent bootloader, the firmware that starts your Pi. Many Pi 4 boards still have the one they shipped with and won't start umbrelOS until it's updated. See Updating your Raspberry Pi's bootloader. It takes about five minutes, and you can use the same microSD card you'll install umbrelOS on.

Install umbrelOS

1. Download the latest umbrelOS image for Raspberry Pi. The same file works on the Pi 5 and Pi 4.
2. Download and install Raspberry Pi Imager or Balena Etcher on your computer.
3. Insert your microSD card into your computer.
4. Open your flashing tool, select the umbrelOS image, select your microSD card, and flash it.
5. Safely eject the card from your computer.

Boot your Raspberry Pi

1. Insert the microSD card into your Raspberry Pi.
2. Leave any USB drives unplugged for now. You can add them once setup is done.
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 and create your account.

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

Add a USB drive for more storage

Once umbrelOS is set up, plug in a USB drive. An SSD is best. It shows up under External storage in Files, where you can keep files on it, give apps access to its folders, or move supported apps onto it to free up space on your microSD card. See External storage.

If a USB drive is already connected when you first set up umbrelOS, setup asks you to Select main storage. Choose SD card. Your apps and files stay on the card, and the drive shows up in Files as external storage.

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.

Running umbrelOS from a USB drive

You can try running umbrelOS from a USB drive, or from an NVMe drive on a Pi 5, instead of a microSD card. It works on many setups but not all of them, so we recommend a microSD card for now. To try it, flash umbrelOS onto the drive instead of a card, remove any microSD card, and start your Pi with the drive connected.

If your Pi doesn't start from the drive and its green light keeps blinking 7 times, you've run into a bug in the Raspberry Pi's own startup software, not a problem with umbrelOS or your drive. It affects the Raspberry Pi 4 when it starts from a USB drive, and updating the bootloader doesn't fix it. We've reported it to Raspberry Pi. Once they fix it, we'll include the fix in an umbrelOS update. Until then, run umbrelOS from a microSD card and use your drive as extra storage.

If you already flashed umbrelOS onto a USB drive, unplug it, flash your microSD card, and set up umbrelOS from the card. Then plug the drive back in. It still holds the old umbrelOS copy, so right-click it under External storage in Files and choose Format before you use it for storage. This erases the drive.

Notes

• Bootloader updates. If your Pi doesn't start umbrelOS from the microSD card, its bootloader may be out of date. This is common on Pi 4 boards and can happen on early Pi 5 boards. See Updating your Raspberry Pi's bootloader.
• Always use the official power supply. Third-party supplies can cause stability issues, especially with a USB drive plugged in.
• Storage Manager and FailSafe aren't available on Raspberry Pi. umbrelOS runs from the microSD card and stores your apps and data on it.
• Keep a backup. microSD cards are slower than SSDs and wear out over time. Back up your Umbrel regularly, for example to a USB drive.
• Machines run ARM versions of each operating system. On a Pi, Machines offers Ubuntu, Fedora, Debian, Alpine, Android, and Windows 11 for ARM.