Run UBOS on Raspberry Pi 2 or 3


You can run UBOS on your Raspberry Pi 2 or 3 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 in Run UBOS in an ARMv7 Linux container (e.g. Raspberry Pi 2, 3, 4).)

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 Raspberry Pi Zero or 1 (discontinued). For the Raspberry Pi 4, go to Run UBOS on Raspberry Pi 4.

You may be able to run UBOS from an external USB stick or disk, if your Raspberry Pi 3’s boot loader is fairly recent. We suggest to use an SD card first, and only try to boot from an external USB stick or disk once you have UBOS booting from the SD card.

To install UBOS on a Raspberry Pi 2 or 3:

  1. Download a UBOS boot image from the Depot. Images for the Raspberry Pi 2 and 3 are at Look for a file named ubos_green_armv7h-rpi2_LATEST.img.xz.

  2. Optionally, you may now verify that your image downloaded correctly by following 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-rpi2_LATEST.img.xz

    on the command line.

  4. Write this image file “raw” to an SD card appropriate for your Raspberry Pi. 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. If this is impractical, create a UBOS Staff by following The UBOS Staff, so you can securely log in over the network without the need for monitor or keyboard.

  6. Remove the SD card and insert it into your Raspberry Pi. If you created a UBOS Staff, insert it into a USB port.

  7. Connect Ethernet to your Raspberry Pi and your Ethernet network.

  8. Plug in the Raspberry Pi’s USB power.

  9. When the boot process is finished, log in as user root from the attached keyboard and monitor. For password, see I need root. If you used a UBOS Staff, you can log in over the network instead as described in The UBOS Staff.

  10. 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 5 or 10 minutes. To determine whether UBOS ready, execute:

    % systemctl is-system-running
  11. Check that your Raspberry Pi has acquired an IP address:

    % ip addr

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

  12. Update UBOS to the latest and greatest:

    % sudo ubos-admin update
  13. You are now ready for Setting up your first Site and App.