Run UBOS on Raspberry Pi 4ΒΆ

You can run UBOS on your Raspberry Pi 4 by downloading an image, writing it to an SD card, and booting your Raspberry Pi with that card. (Alternatively you can keep running your existing Linux distro on your Raspberry Pi, and run UBOS in a Linux container. This is described here.)

All Raspberry Pi 4 models should work out of the box.

If you are not sure which model you have, consult this page.

If you have the original Raspberry Pi or the Raspberry Pi Zero, go to this page. For the Raspberry Pi 2 or 3, go to this page.

You can also run UBOS from an external USB stick or disk, if your Raspberry Pi 4’s EEPROM has been updated to a version after that of June 15, 2020. If it hasn’t been yet, or you aren’t certain, run UBOS from an SD card first, and upgrade the EEPROM later as described here.

To install UBOS on a micro-SD card or external USB disk:

  1. Download a UBOS boot image from Images for the Raspberry Pi 4 are at Look for a file named ubos_green_armv7h-rpi4_LATEST.img.xz.

  2. Optionally, you may now verify that your image downloaded correctly by following the instructions at Verify your downloaded UBOS image.

  3. Uncompress the downloaded file. This depends on your operating system, but might be as easy as double-clicking it, or executing

    % sudo xz -d ubos_green_armv7h-rpi4_LATEST.img.xz

    on the command line.

  4. Write this image file “raw” to your micro-SD card or external USB disk. This operation depends on your operating system:

  5. On first boot, it is recommended you have a monitor and keyboard connected to your Raspberry Pi 4. If this is impractical, create a UBOS staff so you can securely log in over the network without the need for monitor or keyboard.

  6. Remove the micro-SD card and insert it into your Raspberry Pi 4 (or remove any micro-SD card and connect your external USB disk via USB). If you created a UBOS staff, insert the UBOS staff into the USB port. Then, plug in the Raspberry Pi 4’s USB power.

  7. When the boot process is finished, log in as user root (for password, see the user FAQ). If you used a UBOS staff, you can log in over the network instead as described here.

  8. Now: wait. UBOS needs to generate a few cryptographic keys before it is ready to use and initialize a few other things on the first boot. That might take a few minutes. To determine whether UBOS ready, execute:

    % systemctl is-system-running

    Wait until the output has changed from starting to running. If it is anything else, consult troubleshooting.

  9. If you have Ethernet plugged in, and your network has a DHCP server (most networks do), your computer should automatically acquire an IP address. You can check with:

    % ip addr

    Make sure you are connected to the internet before attempting to proceed.

  10. Update UBOS to the latest and greatest:

    % sudo ubos-admin update
  11. You are now ready to set up your first app and site.