Table of Contents
With the release of the Raspberry Pi 2 Model B and its ARMv7-based BCM2709 processor, it is now possible to run Ubuntu directly on the Raspberry Pi.
Note that the information on this page currently only applies to the (ARMv7 and ARMv8) Raspberry Pis: 2B, 3B, 3A+, 3B+, 4B, Compute Module 3, and Compute Module 3+. The original (ARMv6) based Raspberry Pis, including the A, B, B+, 0 and 0W, are not supported under Ubuntu.
Snappy Ubuntu Core
Snappy Ubuntu Core is a new rendition of Ubuntu with transactional updates - a minimal server image with the same libraries as today’s Ubuntu, but applications are provided through a simpler mechanism. Images are available for the Raspberry Pi 2 and 3.
These are not Ubuntu Core images, but the 'classic' deb based image.
18.04 LTS: ubuntu-18.04.3-preinstalled-server-armhf+raspi3.img.xz (4G image, 440MB compressed)
19.10.1: ubuntu-19.10.1-preinstalled-server-armhf+raspi3.img.xz (4G image, 613MB compressed)
18.04 LTS: ubuntu-18.04.3-preinstalled-server-arm64+raspi3.img.xz (4G image, 441MB compressed)
19.10.1: ubuntu-19.10.1-preinstalled-server-arm64+raspi3.img.xz (4G image, 632MB compressed)
Further releases can be found at http://cdimage.ubuntu.com/ubuntu/releases/. Please note that even though these images are labelled "+raspi3" they are compatible with the Raspberry Pi 2 and 3 (and 4 in the case of 19.10).
There is a "+raspi2" image available for 18.04, however new users are strongly discouraged from using this; use the "+raspi3" image instead (as noted above this is compatible with all supported variants). The "+raspi2" image is provided for continuity purposes only and should be avoided for new installs.
Installation is the same as other Raspberry Pi images; a generic installation guide from raspberrypi.org is available here.
WARNING: These commands have the potential to wipe your hard drive!
xzcat ubuntu.img.xz | sudo dd bs=4M of=/dev/mmcblk0
Or using ddrescue (must decompress the image first):
unxz ubuntu.img.xz sudo ddrescue -D -d --force ubuntu.img /dev/mmcblk0
First boot (Username/Password)
The login username is "ubuntu", password is "ubuntu". You will be asked to change the password on first login.
Alternatively, you may wish to customize the initial user by editing the cloud-init configuration before first boot. To do so, remove and re-insert your freshly written SD card, then edit the "user-data" file on the "system-boot" partition. This is a text file in YAML format with several examples contained in comments.
Raspberry Pi packages
Although the majority of the Raspberry Pi cloud/server image works like any other Ubuntu system, there are a few packages that you may not be familiar with. Briefly:
linux-firmware-raspi2 - GPU firmware bootloader files and WiFi firmware configuration files
linux-raspi2 (linux-image-raspi2) - Linux kernel with patches from https://github.com/raspberrypi/linux
u-boot-rpi - Provides the various uboot* binaries under /boot/firmware
flash-kernel - Automatically copies the latest kernel, dtb file and u-boot script to the pi's fat formatted GPU firmware partition
The GPU firmware partition is mounted at /boot/firmware. The /boot/firmware/config.txt file contains the system configuration and refers to several other files within /boot/firmware. Note, it is likely that you will have to adapt third party instructions to these file locations.
While the official image includes compatible firmware, bootloader and kernel, there are a few packages available in an unofficial PPA (ppa:ubuntu-raspi2/ppa) which are useful on the Raspberry Pi, including:
libraspberrypi-bin-nonfree - Binary VideoCore utilities not provided in the open source userland repository, currently vcdbg and edidparser.
xserver-xorg-video-fbturbo - An accelerated x.org video driver, though this is limited to hardware accelerated window moving/scrolling on the Raspberry Pi.
hello-dkms - Not strictly to do with the Raspberry Pi, but a small example DKMS project to test building kernel DKMS modules.
sudo add-apt-repository ppa:ubuntu-raspi2/ppa sudo apt-get update
Further/updated Raspberry Pi packages can be found in the Ubuntu Pi Flavour Maker PPA. Many of these packages rely on the user being a member of groups:
sudo groupadd -f --system gpio sudo groupadd -f --system i2c sudo groupadd -f --system input sudo groupadd -f --system spi
This is a small ubuntu-server image. If you want a full desktop, go ahead and do so:
$ sudo apt-get install xubuntu-desktop # or $ sudo apt-get install lubuntu-desktop # or $ sudo apt-get install kubuntu-desktop # etc
Tasks can be installed with Tasksel.
Accelerated X driver
An accelerated x.org video driver is available (fbturbo), though this is limited to hardware accelerated window moving/scrolling on the Raspberry Pi. Install the optional PPA above, then:
$ sudo apt-get install xserver-xorg-video-fbturbo
Then add this to /etc/X11/xorg.conf (create if it doesn't already exist):
Section "Device" Identifier "Raspberry Pi FBDEV" Driver "fbturbo" Option "fbdev" "/dev/fb0" Option "SwapbuffersWait" "true" EndSection
As with Raspbian, VideoCore packages are available. Install the optional PPA above, then:
$ sudo apt-get install libraspberrypi-bin libraspberrypi-dev
However, since these packages are compiled from source during build, the files are installed in their "proper" locations in /usr. Some third-party scripts may expect e.g. /opt/vc/bin/vcgencmd; if so, this hack should do it:
$ sudo ln -s /usr /opt/vc
(Raspbian packages use precompiled repositories during build, which install in /opt/vc.) vcdbg and edidparser are not part of the open source package and must be installed separately:
$ sudo apt-get install libraspberrypi-bin-nonfree
Change the bootloader
The official Ubuntu images use u-boot as the bootloader. However, the Pi's own built in bootloader can be used with a few changes to the config.txt file on the system-boot partition.
Write the image to an SD card as normal, but before you insert it into the Pi, re-insert the SD card so that you can make changes. Open the config.txt on the first partition (labelled system-boot). Change the kernel line(s), add an initramfs line, and comment out (#) the device_tree_address line as follows:
kernel=vmlinuz initramfs initrd.img followkernel #device_tree_address=0x03000000
The second partition contains the Linux root filesystem. Copy the dtb file for your machine (e.g. bcm2710-rpi-3-b.dtb) plus the overlay folder if needed from /lib/firmware/4.X.X-XXXX-raspi2/device-tree to the system-boot partition.
Place the SD card in your Pi and turn on!
Update flash-kernel database
The flash-kernel package is used to copy the kernel and initrd to the fat system-boot partition.
If your new machine is missing from the flash-kernel database ("unsupported platform" error message when you update the kernel) then add an entry to /etc/flash-kernel/db. The full database can be found at /usr/share/flash-kernel/db/all.db. For the Machine field use the output of:
cat /proc/device-tree/model ; echo
An example entry for the Raspberry Pi 3 Model B Plus would be:
Machine: Raspberry Pi 3 Model B Plus DTB-Id: bcm2710-rpi-3-b-plus.dtb Boot-DTB-Path: /boot/firmware/bcm2710-rpi-3-b-plus.dtb Boot-Kernel-Path: /boot/firmware/vmlinuz Boot-Initrd-Path: /boot/firmware/initrd.img
If you need to manually copy across the kernel and initrd files (note, the system-boot partition is mounted at /boot/firmware):
sudo cp /boot/vmlinuz /boot/firmware/ sudo cp /boot/initrd.img /boot/firmware/
The Raspberry Pi 3 (and Pi 2 v1.2 with the same BCM2837 SoC as the Pi3) is capable of booting from a USB drive. To do this you'll first need to program USB boot mode (this is unnecessary on the 3B+ as USB booting is on by default). For the original Pi 2, or if you are having problems with USB booting, then you can copy the bootcode.bin file to an SD card and place all other files on a USB drive.
You must have bootloader files (confusingly referred to as the firmware on the Raspberry Pi) from after April 2017. So if necessary grab the latest bootcode.bin, fixup.dat and start.elf and copy them to your system-boot partition.
Edit the cmdline.txt file and change root=/dev/mmcblk0p2 to root=LABEL=writable (or root=LABEL=cloudimg-rootfs for the raspi2 images). If you are using a lot of drives then you may wish to switch to using the UUID of the partition.
If you haven't already done so, change the bootloader, as Ubuntu's u-boot script is hard coded for SD card use.
Since 18.04.2 the linux-firmware and linux-firmware-raspi2 packages now contain the necessary files for the built-in WiFi on the Pi 3B, 3B+, and 4B. However, if for some reason you want the latest and greatest files:
mkdir wifi-firmware cd wifi-firmware # Pi 3B wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43430-sdio.bin wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43430-sdio.clm_blob wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43430-sdio.txt # Pi 3B+ and 4 wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43455-sdio.bin wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43455-sdio.clm_blob wget https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm/brcmfmac43455-sdio.txt sudo cp *sdio* /lib/firmware/brcm/ cd ..
Reboot the machine.
Use dpkg-divert to stop these files being overwritten on package updates.
'arm64' is the Debian port name for the 64-bit ARMv8 architecture, referred to as 'aarch64' in upstream toolchains (GNU triplet aarch64-linux-gnu), and some other distros.
BCM2837 is the chip used in the Raspberry Pi 3 and in later models of the Raspberry Pi 2 (board revision V1.2). It packages a 64-bit quad-core ARM Cortex A53 (ARMv8) CPU with VideoCore IV GPU.
There is a config.txt entry to make the ARM start in 64-mode (otherwise 32-bit mode is used):
(This will fail to boot unless you provide a kernel/uboot compiled for 64-bit mode)
64 bit versions of the linux-raspi2 kernels were introduced in Ubuntu 16.10 (Yakkety Yak).
To set up MultiArch:
sudo dpkg --add-architecture arm64 sudo apt update
Install the 64 bit kernel:
sudo apt install linux-image-raspi2:arm64
Edit the config.txt to start in 64-bit mode (see above). Reboot.
Install any other packages you want e.g. to run 64-bit Firefox:
sudo apt install firefox:arm64
Booting generic arm64 ISO images
The generic arm64 linux kernels can also be used with a suitable bootloader. For example, the Xenial hwe-mini.iso, Bionic mini.iso and ubuntu-18.04-server-arm64.iso can be booted with a u-boot-UEFI-grub2 combination. This can be achieved as follows:
Create a partition with pi firmware/bootloader files
The Raspberry Pi's bootloader, built into the GPU and non-updateable, only has support for reading from FAT filesystems (both FAT16 and FAT32). So the first step is to create a partition on a SD card or USB device and format it as FAT. The partition can be physically anywhere on the disk, but to ensure it is bootable on the Pi it should be given partition number 1 on a MBR/msdos partition table.
Next, download and copy across the GPU firmware and bootloader files (start*.elf, fixup*.dat and bootcode.bin). See the instructions above.
Ubuntu includes an ARM cross compiler than can be used to compile U-boot for the RPi:
sudo apt install git make gcc gcc-aarch64-linux-gnu git clone --depth 1 git://git.denx.de/u-boot.git cd u-boot make rpi_3_defconfig make CROSS_COMPILE=aarch64-linux-gnu-
Copy it to the partition:
sudo mount /dev/XXX1 /mnt sudo cp u-boot.bin /mnt/kernel8.img cd ..
Calling it kernel8.img means that 64-bit mode is automatically used.
Copy the device tree blob
An optional stage is to provide a dtb file:
wget http://ports.ubuntu.com/dists/bionic/main/installer-arm64/current/images/device-tree/bcm2837-rpi-3-b.dtb sudo mkdir -p /mnt/dtb/broadcom/ sudo cp bcm2837-rpi-3-b.dtb /mnt/dtb/broadcom/
Copy the ISO contents to the FAT partition
You can use dd to burn the ISO to a separate USB flash drive, but if you don't have a spare flash drive, then you can combine the contents of the ISO with the bootloader files. The following downloads the mini ISO and copies all the files from it:
wget http://ports.ubuntu.com/dists/bionic/main/installer-arm64/current/images/netboot/mini.iso mkdir /tmp/mini-iso sudo mount -o loop mini.iso /tmp/mini-iso sudo cp -rT /tmp/mini-iso /mnt
Note, if you are doing this via a graphical file manager then you must ensure you copy the hidden .disk folder.
Finally extract the bootaa64.efi file and copy it across:
mkdir /tmp/efi-img sudo mount -o loop /tmp/mini-iso/boot/grub/efi.img /tmp/efi-img sudo cp -rT /tmp/efi-img /mnt sync sudo umount /tmp/efi-img sudo umount /tmp/mini-iso sudo umount /mnt
Booting and installation
Before booting the installer it's worth taking a bit of time to plan how you want the system to work. The installed system could use the linux-raspi2 kernel with flash-kernel (recommended), or the generic kernel with grub2. These require different partition mount points, and possibly the use of boot parameters.
The installer partitioner wants to create by default a GPT partition table which is unbootable on the Pi. To change this to a MBR/msdos partition table you can use the boot parameter:
Once you are ready, insert the device containing the bootloader files (plus the dd'd USB flash drive if that's what you've done) into the Raspberry Pi and power on! Make your selection at the grub2 menu, adding any installer boot parameters before the ' --- ' as necessary. Note, once you've made your selection via the grub menu, there can be a long blank screen interval before the installer shows on the screen.
Linux-raspi2 kernel with flash-kernel
To use flash-kernel use the boot parameter:
At the partitioning stage, the pi's fat partition should be given the mount point /boot/firmware.
Currently the installer cannot be made to install linux-raspi2 kernel. As a consequence the installer is likely to fail at the installing bootloader stage. If this happens drop to a shell using the installer menu option. From here
mount -o bind /dev /target/dev #This next command turns the screen black. Wait for the cursor to appear in the bottom left of the screen. #Install the meta package linux-raspi2 if you need the header packages apt-install linux-image-raspi2 umount /target/dev exit
If you've booted the installer using a HWE kernel then it is recommended you postpone installing a desktop until after you've rebooted into your system and have removed the generic-hwe kernel packages.
Complete the installation by manually copying the Pi's GPU firmware/bootloader files to the fat partition. You'll also need to setup a config.txt and cmdline.txt. Remove the generic kernel packages once successfully booted.
Generic kernel with grub2
At the partitioning stage set the bootable flag on the pi's fat partition and use the mount point /boot/efi. The Raspberry Pi cannot boot from an EFI partition type (a fat partition with the esp flag set). If the debian installer sets a partition to this type, then after the install use gParted to remove the esp flag so that it is bootable on the Pi.
Complete the installation by manually copying the Pi's GPU firmware/bootloader files to the fat partition and copy u-boot as before to act as uefi.
Recovering a system using the generic kernel
This maybe required if the installing bootloader stage fails and has been skipped.
You could re-run the installer, selecting the rescue option. Alternatively, if you are familiar with grub2 and are using the generic kernel then the installed system can be booted directly with the installer grub2 files. For example, boot the installer but at the grub2 command-line interface prompt:
ls set root=(hd1,msdos2) ls / linux /boot/vmlinuz root=/dev/mmcblk0p2 ro initrd /boot/initrd.img boot
To install grub2:
#pass the --removable or --no-nvram options to grub-install sudo grub-install --no-nvram sudo update-grub
Raspberry Pi 3 B+ (2018) functionality is not yet available with these images.
Raspberry Pi 3: ubuntu-18.04-preinstalled-server-armhf+raspi3.img.xz (4G image, 296M compressed)
- Updated 2018-04-28 (18.04 LTS)
Raspberry Pi 3: ubuntu-16.04-preinstalled-server-armhf+raspi3.img.xz (4G image, 252M compressed)
- Updated 2018-04-21 (16.04.4 LTS)
Building Raspberry Pi 3 images
To build a Raspberry Pi 3 image, you will need an armhf 18.04 LTS (bionic) build host (or chroot) and a fair amount of working space (at least 10GB).
Branch lp:~fo0bar/livecd-rootfs/raspi2-rpi3, build its .deb and install it.
apt-get install live-build mkdir -p build/chroot cd build cp -a /usr/share/livecd-rootfs/live-build/auto . export ARCH=armhf export SUITE=xenial # or bionic # export MIRROR=http://deb-proxy.local/ubuntu-ports # if you have a local caching proxy export IMAGEFORMAT=ext4 export SUBARCH=raspi3 export PROJECT=ubuntu-cpc export EXTRA_PPAS="ubuntu-raspi2/ppa-rpi3" lb config lb build
Ubuntu 14.04 LTS
An Ubuntu 14.04 LTS (Trusty Tahr) image is available for the Raspberry Pi 2, which combines the released 14.04 distribution with a PPA containing kernels and firmware which work on the Raspberry Pi 2.
This image, along with the one-off kernel it installs, is no longer maintained. Please use the 16.04 Xenial image instead.
- 152MiB ZIP, 1.75GiB uncompressed image
- Login username is "ubuntu", password is "ubuntu"
- Raspberry Pi 3 images are not available.
There are no Raspbian-specific utilities included, specifically no automatic root resizer. However, it's not hard to do manually. Once booted:
$ sudo fdisk /dev/mmcblk0
Delete the second partition (d, 2), then re-create it using the defaults (n, p, 2, enter, enter), then write and exit (w). Reboot the system, then:
$ sudo resize2fs /dev/mmcblk0p2
There is no swap partition/file included. If you want swap, it's recommended you do:
$ sudo apt-get install dphys-swapfile
You should have a (resized) SD card at least 4GB, because by default it will want to create a ~2GB swapfile.
If you are using a wifi dongle, you will likely need to get the linux-firmware package:
$ sudo apt-get install linux-firmware
If you would like to install an SSH server for remote access:
$ sudo apt-get install openssh-server
To enable the serial console, change the /boot/cmdline.txt as follows:
dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootwait
and add a new file /etc/init/ttyAMA0.conf:
start on stopped rc or RUNLEVEL= stop on runlevel [!12345] respawn exec /sbin/getty -L 115200 ttyAMA0 vt102
The kernel used by the Raspberry Pi 2 port is an Ubuntu-style kernel package of an "rpi2" flavor, e.g. linux-image-3.18.0-20-rpi2. Currently it is comprised of the following functionality:
- Mainline 3.18.x
- Provides extra functionality such as aufs
- Also includes additional stability fixes, many of which have been rolled into mainline post-3.18.7
Raspberry Pi-specific patches from the rpi-3.18.y branch of Raspberry Pi's linux git tree
Ubuntu's 3.18 development is no longer active, as they moved on to 3.19 to be released with 15.04 vivid. However, mainline 3.18 was designated an LTS kernel release, and is still getting active security/stability updates. Because of this, 3.18 will likely remain the "supported" kernel of this port. (Again, this is an unofficial port and no support guarantee is implied.)
The script used to build the images is available here.
If you want to build an image on your x86 Ubuntu host, install qemu-user-static package and edit the script to use "qemu-debootstrap --arch armhf" instead of "debootstrap":
qemu-debootstrap --arch armhf $RELEASE $R http://ports.ubuntu.com/
Cross-upgrading 14.04 to 16.04
You can upgrade an old unofficial 14.04 installation to the official 16.04 installation, though it takes a number of additional steps.
Note that Ubuntu's setup uses u-boot as an intermediary bootloader, which is different from the previous system of the RPI2 booting the kernel directly. This will be reflected in the upgrade procedure.
Once you begin this procedure, if you reboot the installation without completing the entire upgrade procedure, you will be left with an unbootable system.
First, remove a number of PPA packages which are obsoleted / incompatible with the 16.04.
apt-get --purge remove rpi2-ubuntu-errata raspberrypi-bootloader-nokernel \ linux-image-rpi2 flash-kernel
Back up and remove the apt PPA configuration and module blacklists (the latter will be provided directly by the 4.4.0 kernel package).
mkdir -p /root/xenial-upgrade tar zcvf /root/xenial-upgrade/etc.tar.gz \ /etc/modprobe.d/rpi2.conf \ /lib/modules-load.d/rpi2.conf \ /etc/apt/preferences.d/rpi2-ppa \ /etc/apt/sources.list.d/fo0bar-rpi2* \ /etc/apt/trusted.gpg.d/fo0bar-rpi2* rm -f \ /etc/modprobe.d/rpi2.conf \ /lib/modules-load.d/rpi2.conf \ /etc/apt/preferences.d/rpi2-ppa \ /etc/apt/sources.list.d/fo0bar-rpi2* \ /etc/apt/trusted.gpg.d/fo0bar-rpi2*
Back up and remove the contents of /boot/firmware, which will be recreated.
tar zcvf /root/xenial-upgrade/firmware.tar.gz /boot/firmware/* rm -rf /boot/firmware/*
Update apt sources without the old PPA configuration.
Run do-release-upgrade as normal. When asked to reboot at the end, do not, and select "n" instead.
do-release-upgrade -d # -d will be unneeded once 16.04.1 is released
Install new firmware, u-boot and 4.4.0 kernel metapackages.
apt-get install u-boot-rpi u-boot-tools linux-raspi2 linux-firmware-raspi2 \ linux-firmware flash-kernel
Install the RPI2 DT-compatible u-boot image.
apt-get install binutils # for "strings" wget -O /tmp/mkknlimg https://raw.githubusercontent.com/raspberrypi/linux/rpi-4.4.y/scripts/mkknlimg chmod 0755 /tmp/mkknlimg /tmp/mkknlimg --dtok /usr/lib/u-boot/rpi_2/u-boot.bin /boot/firmware/uboot.bin
Install basic config.txt and cmdline.txt configurations. If your root device is not on the second SD partition (uncommon) or you have a more advanced configuration, recreate them here.
cat <<"EOM" >/boot/firmware/config.txt kernel=uboot.bin dtparam=i2c_arm=on dtparam=spi=on EOM cat <<"EOM" >/boot/firmware/cmdline.txt net.ifnames=0 dwc_otg.lpm_enable=0 console=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait EOM
Update the initrd and re-flash the kernel configuration.
update-initramfs -u flash-kernel
Optionally add ppa:ubuntu-raspi2/ppa as described above.