Edit the Raspberry Pi boot configuration¶

The Raspberry Pi’s boot configuration consists of a series of simple text files. Depending on the model of Pi, the boot configuration either exists entirely on the boot partition (the first FAT-formatted partition on your boot media), or has a portion based in a boot EEPROM (on the Pi 4 and 5).

The format of the boot configuration is based on the classic MS-DOS INI-format, with the following variations:

Section and property names are case sensitive
Comments start with a hash-sign (#), not a semi-colon (;)
Comments may only start at the beginning of a line, not trailing a property
Ordering of sections and properties is relevant because…
Duplicate names are permitted with later declarations overriding earlier ones
Quoted values are not permitted
Spaces are not permitted (or more precisely are not ignored) either side of the “=” in a key=value setting and hence, should not be used

Main configuration¶

The main boot configuration, which applies to all models of Pi, lives in a file called config.txt placed on the boot partition of your boot media (the first FAT-formatted partition). Typically on Ubuntu, this is mounted under the path /boot/firmware. Files on the partition can only be manipulated by the root user, hence to edit the boot configuration at run-time you would use something like:

sudo vi /boot/firmware/config.txt

Below, we’ll walk through the default boot configuration on Ubuntu Server for Raspberry Pi. This will illustrate the format, and demonstrate a typical (if minimal) configuration example:

[all]
arm_64bit=1
kernel=vmlinuz
cmdline=cmdline.txt
initramfs initrd.img followkernel

Note

The lack of an equals sign in the initramfs line is intentional, and is a quirk of the config.txt format. It only applies to this property.

We start off with the [all] section. As the name implies, this applies to all Pis, whatever model, or serial number. This first block simply defines:

arm_64bit: Informs the bootloader we want to start the ARM cores in 64-bit mode (ARMv8)
kernel: Specifies the location of the Linux kernel (here, vmlinuz on the boot partition)
cmdline: The file containing the command line to pass to the Linux kernel (the single line in cmdline.txt on the boot partition). Be aware that the command line will also include parameters determined by the bootloader itself. If you query /proc/cmdline at run-time you should typically find the content of cmdline.txt is present as a suffix
initramfs: The archive containing the initial ram-disk (the content of the initial root file-system), and where to load it in memory. Here, we tell the bootloader to place it immediately after the kernel

# Enable the audio output, I2C and SPI interfaces on the GPIO header. As these
# parameters related to the base device-tree they must appear *before* any
# other dtoverlay= specification
dtparam=audio=on
dtparam=i2c_arm=on
dtparam=spi=on

We carry on, still in the [all] section, with a series of dtparam lines. These are device-tree parameters which customize the base device-tree. In this case these enable the ALSA, I²C, and SPI interfaces.

# Enable the KMS ("full" KMS) graphics overlay, leaving GPU memory as the
# default (the kernel is in control of graphics memory with full KMS)
dtoverlay=vc4-kms-v3d
disable_fw_kms_setup=1

Next are a series of options controlling video output. The two important options are:

dtoverlay: This loads the “full” KMS device-tree overlay, leaving the Linux kernel in control of the display hardware, rather than the boot firmware
disable_fw_kms_setup: This disables the firmware’s detection of the monitor (via EDID), leaving the Linux kernel to handle detection it

# Enable the serial pins
enable_uart=1

This section simply enables the serial UART on GPIO 14 and 15. This is only included on the Ubuntu Server images because headless setups (where the serial console is useful for debugging) are relatively common with this image. See Connect to a UART console for further information.

The Ubuntu Desktop images do not enable the serial UART by default as we assume a keyboard and monitor will be present there.

# Config settings specific to arm64
dtoverlay=dwc2

[pi4]
max_framebuffers=2
arm_boost=1

[pi3+]
# Use a smaller contiguous memory area, specifically on the 3A+ to avoid an
# OOM oops on boot. The 3B+ is also affected by this section, but it shouldn't
# cause any issues on that board
dtoverlay=vc4-kms-v3d,cma-128

[pi02]
# The Zero 2W is another 512MB board which is occasionally affected by the same
# OOM oops on boot.
dtoverlay=vc4-kms-v3d,cma-128

[cm4]
# Enable the USB2 outputs on the IO board (assuming your CM4 is plugged into
# such a board)
dtoverlay=dwc2,dr_mode=host

[all]

Lastly, we have a series of properties and sections that simply apply workarounds for various issues. Mostly, these involve loading device-tree overlays or applying parameters to them. It is noteworthy, however, that there are several sections named after models of Raspberry Pi. This limits their effects only to matching models.

The final line specifies an empty [all] section. If scripts or applications blindly append further options to this file, this ensures they don’t inadvertently wind up only applying to the last filter (for the Compute Module 4, in this case).

Conditional Sections¶

There are several other conditional section types that can be used. Refer to the Raspberry Pi documentation of the config.txt format for the definitive list, but a brief set of examples follows:

[all], [none]: Special sections that apply to all boards and no boards respectively. While seemingly pointless, the [none] section is handy for effectively “commenting out” multiple properties
[pi0], [pi2], [pi4], [cm4], etc.: Sections that limit their effect to the respective model of Raspberry Pi. Please note there are some subtleties here. For instance, the [pi0] section applies to the Pi Zero, Zero W, and Zero 2W. Likewise, the [pi4] section applies to the 4B, 400, and Compute Modules 4 and 4S. Consult the linked documentation above for the specific overlaps
[EDID=Foo-Bar Monitor]: Sections that limit their effect to Raspberry Pis attached to a monitor with the specified EDID name (see the EDID filter section for information on determining your monitor’s EDID name). Useful if you have workarounds that apply only to a specific monitor
[0x12345678]: Sections that apply only to a board with the specified serial number. This can be found at the bottom of /proc/cpuinfo. Only use the last eight hexadecimal digits of the listed serial number
[gpio4=1]: Sections that apply only when the specified GPIO is found in the specified state (1 for high, 0 for low) at boot time.

EEPROM configuration¶

On Raspberry Pi models 4 and later (including the Compute Module 4, the 400, and the Pi 5), there is an additional boot configuration file stored in the boot EEPROM. This is parsed and acted upon prior to config.txt and in many cases determines the boot media on which to find config.txt.

As this configuration is stored in EEPROM, it is not something that ships on Ubuntu images, and will be specific to your board. The default configuration has also evolved over time, so that later models of the Pi have a different default EEPROM configuration to earlier models.

Furthermore, as it only exists in EEPROM, it is not a file accessible via a regular file-system. Use the rpi-eeprom-config utility from the rpi-eeprom package to view the configuration:

sudo rpi-eeprom-config

This utility can also be used to edit the configuration:

sudo rpi-eeprom-config --edit

This will launch your configured text editor (nano(1) or vim(1) by default) with an ephemeral copy of the EEPROM configuration. Upon successful exit, the utility will write the (potentially modified) copy back to the EEPROM.

Note

In some cases (older versions of rpi-eeprom, or where the flashrom(8) utility is not present), a reboot is required to write the configuration to the EEPROM.

The format of the EEPROM configuration is the same as for config.txt above, but the properties are different.

Boot Order¶

By far the most important property for most people, will be BOOT_ORDER. This dictates which boot sources the Pi will attempt to read, and in what order. The value is a 0x prefixed hexadecimal number. Read right to left, each digit specifies a boot source to attempt. The possible boot sources, at the time of writing, are:

Digit	Source	Description
0	Card Detect	Deprecated
1	SD Card	Attempt to boot from the SD card slot, or the eMMC on Compute Modules
2	TFTP	Attempt DHCP over ethernet, then TFTP to retrieve further boot assets
3	RPI BOOT	Attempt USB host boot, where the Pi acts as a device to a USB host. Typically used for flashing eMMC in Compute Modules
4	USB MSD	Attempt USB boot from an attached mass-storage device (MSD); this is the typical mode used to boot from attached SSDs or hard-drives
5	USB MSD (Type-C)	Attempt USB boot from a mass-storage device attached to the USB-C socket; Pi 4 and CM4 only
6	NVMe	Attempt boot from an NVMe device connected to the PCIe interface (CM4 and Pi 5 only)
7	HTTP	Attempt DHCP over ethernet, then HTTP to retrieve further boot assets (this mode is used to launch rpi-imager from the bootloader)
E	Stop	Terminate further boot attempts and display the error pattern; power-cycle is required to continue
F	Loop	Restart the sequence from the initial boot mode

Some typical values are given below:

0xF41: Try SD (1), followed by USB MSD (4), then repeat (F). This is the default boot order on modern Raspberry Pis
0xF14: Try USB MSD (4), followed by SD (1), then repeat (F)
0xF461: Try SD (1), followed by NVMe (6), USB MSD (4), then repeat (F)
0xF21: Try SD (1), followed by TFTP network, then repeat

Warning

We would strongly recommend leaving the SD card (1) somewhere in the boot order, to ensure that in the event of invalid configuration you always have a simple means of booting a rescue image to reconfigure things.

For example, if you configure BOOT_ORDER=0xF2 (network, then retry), but fail to correctly configure a TFTP network boot for your Pi, it is more difficult to recover (though usually still possible with the official recovery image).