The config.txt file is read by the early-stage boot firmware, so it uses a very simple file format: a single property=value statement on each line, where value is either an integer or a string. Comments may be added, or existing config values may be commented out and disabled, by starting a line with the # character.

There is a 98-character line length limit for entries. Raspberry Pi OS ignores any characters past this limit.

Here is an example file:

Specifies the partition number for booting unless the partition number was already specified as a parameter to the reboot command (e.g. sudo reboot 2).

Partition numbers start at 1 and the MBR partitions are 1 to 4. Specifying partition 0 means boot from the default partition which is the first bootable FAT partition.

Bootable partitions must be formatted as FAT12, FAT16 or FAT32 and contain a start.elf file (or config.txt file on Raspberry Pi 5) in order to be classed as be bootable by the bootloader.

This filter passes if the system was booted with the tryboot flag set.

Set this property to 1 to load the normal config.txt and boot.img files instead of tryboot.txt and tryboot.img when the tryboot flag is set.

This enables the tryboot switch to be made at the partition level rather than the file-level without having to modify configuration files in the A/B partitions.

The following pseudo-code shows how a hypothetical OS Update service could use tryboot in autoboot.txt to perform a fail-safe OS upgrade.

Initial autoboot.txt:

Installing the update

Committing or cancelling the update

Updated autoboot.txt:

audio_pwm_mode=1 selects legacy low-quality analogue audio from the 3.5mm AV jack.

audio_pwm_mode=2 (the default) selects high quality analogue audio using an advanced modulation scheme.

By default, a 1.0LSB dither is applied to the audio stream if it is routed to the analogue audio output. This can create audible background hiss in some situations, for example when the ALSA volume is set to a low level. Set disable_audio_dither to 1 to disable dither application.

Audio dither (see disable_audio_dither above) is normally disabled when the audio samples are larger than 16 bits. Set this option to 1 to force the use of dithering for all bit depths.

The pwm_sample_bits command adjusts the bit depth of the analogue audio output. The default bit depth is 11. Selecting bit depths below 8 will result in nonfunctional audio, as settings below 8 result in a PLL frequency too low to support. This is generally only useful as a demonstration of how bit depth affects quantisation noise.

cmdline is the alternative filename on the boot partition from which to read the kernel command line string; the default value is cmdline.txt.

kernel is the alternative filename on the boot partition for loading the kernel. The default value on the Raspberry Pi 1, Zero and Zero W, and Raspberry Pi Compute Module 1 is kernel.img. The default value on the Raspberry Pi 2, 3, 3+ and Zero 2 W, and Raspberry Pi Compute Modules 3 and 3+ is kernel7.img. The default value on the Raspberry Pi 4 and 400, and Raspberry Pi Compute Module 4 is kernel8.img, or kernel7l.img if arm_64bit is set to 0.

The Raspberry Pi 5 firmware defaults to loading kernel_2712.img because this image contains optimisations specific to Raspberry Pi 5 (e.g. 16K page-size). If this file is not present, then the common 64-bit kernel (kernel8.img) will be loaded instead.

If set to 1, the kernel will be started in 64-bit mode. Setting to 0 selects 32-bit mode.

In 64-bit mode, the firmware will choose an appropriate kernel (e.g. kernel8.img), unless there is an explicit kernel option defined, in which case that is used instead.

Defaults to 1 on Raspberry Pi 4, 400 and Compute Module 4, 4S platforms. Defaults to 0 on all other platforms. However, if the name given in an explicit kernel option matches one of the known kernels then arm_64bit will be set accordingly.

64-bit kernels come in the following forms:

Both forms may use the img file extension; the bootloader recognizes archives using signature bytes at the start of the file.

The following Raspberry Pi models support this flag:

Later models, such as Raspberry Pi 5, only support the 64-bit kernel. Such models do not support this flag.

ramfsfile is the optional filename on the boot partition of a ramfs to load.

ramfsaddr is the memory address to which the ramfsfile should be loaded.

The initramfs command specifies both the ramfs filename and the memory address to which to load it. It performs the actions of both ramfsfile and ramfsaddr in one parameter. The address can also be followkernel (or 0) to place it in memory after the kernel image. Example values are: initramfs initramf.gz 0x00800000 or initramfs init.gz followkernel. As with ramfsfile, newer firmwares allow the loading of multiple files by comma-separating their names.

If auto_initramfs is set to 1, look for an initramfs file using the same rules as the kernel selection.

By default, a probe on the I2C bus will happen at startup, even when a PoE HAT is not attached. Setting this option to 1 disables control of a PoE HAT fan through I2C (on pins ID_SD & ID_SC). If you are not intending to use a PoE HAT, this is a helpful way to minimise boot time.

If disable_splash is set to 1, the rainbow splash screen will not be shown on boot. The default value is 0.

enable_uart=1 (in conjunction with console=serial0,115200 in cmdline.txt) requests that the kernel creates a serial console, accessible using GPIOs 14 and 15 (pins 8 and 10 on the 40-pin header). Editing cmdline.txt to remove the line quiet enables boot messages from the kernel to also appear there. See also uart_2ndstage.

Set this option to 0 to prevent the firmware from trying to read an I2C HAT EEPROM (connected to pins ID_SD & ID_SC) at powerup. See also disable_poe_fan.

os_prefix is an optional setting that allows you to choose between multiple versions of the kernel and Device Tree files installed on the same card. Any value in os_prefix is prepended to the name of any operating system files loaded by the firmware, where "operating system files" is defined to mean kernels, initramfs, cmdline.txt, .dtbs and overlays. The prefix would commonly be a directory name, but it could also be part of the filename such as "test-". For this reason, directory prefixes must include the trailing / character.

In an attempt to reduce the chance of a non-bootable system, the firmware first tests the supplied prefix value for viability - unless the expected kernel and .dtb can be found at the new location/name, the prefix is ignored (set to ""). A special case of this viability test is applied to overlays, which will only be loaded from ${os_prefix}${overlay_prefix} (where the default value of overlay_prefix is "overlays/") if ${os_prefix}${overlay_prefix}README exists, otherwise it ignores os_prefix and treats overlays as shared.

(The reason the firmware checks for the existence of key files rather than directories when checking prefixes is twofold: the prefix may not be a directory, and not all boot methods support testing for the existence of a directory.)

See also overlay_prefix and upstream_kernel.

USB On-The-Go (often abbreviated to OTG) is a feature that allows supporting USB devices with an appropriate OTG cable to configure themselves as USB hosts. On older Raspberry Pis, a single USB 2 controller was used in both USB host and device mode.

Raspberry Pi 4B and Raspberry Pi 400 (not CM4 or CM4IO) add a high performance USB 3 controller, attached via PCIe, to drive the main USB ports. The legacy USB 2 controller is still available on the USB-C power connector for use as a device (otg_mode=0, the default).

otg_mode=1 requests that a more capable XHCI USB 2 controller is used as another host controller on that USB-C connector.

Specifies a subdirectory/prefix from which to load overlays, and defaults to overlays/ (note the trailing /). If used in conjunction with os_prefix, the os_prefix comes before the overlay_prefix, i.e. dtoverlay=disable-bt will attempt to load ${os_prefix}${overlay_prefix}disable-bt.dtbo.

Raspberry Pi 5 requires a config.txt file to be present to indicate that the partition is bootable.

The following config.txt properties are used to program the secure-boot OTP settings. These changes are irreversible and can only be programmed via RPIBOOT when flashing the bootloader EEPROM image. This ensures that secure-boot cannot be set remotely or by accidentally inserting a stale SD card image.

For more information about enabling secure-boot please see the Secure Boot readme and the Secure Boot tutorial in the USBBOOT repo.

This table gives the default values for the options on various Raspberry Pi models, all frequencies are stated in MHz.

This table gives defaults for options which are the same across all models.

The firmware uses Adaptive Voltage Scaling (AVS) to determine the optimum CPU/GPU core voltage in the range defined by over_voltage and over_voltage_min.

The minimum core frequency when the system is idle must be fast enough to support the highest pixel clock (ignoring blanking) of the display(s). Consequently, core_freq will be boosted above 500 MHz if the display mode is 4Kp60.

To view the temperature of a Raspberry Pi, run the following command:

Divide the result by 1000 to find the value in degrees Celsius. Alternatively, you can use vcgencmd measure_temp to report the GPU temperature.

Hitting the temperature limit is not harmful to the SoC, but it will cause the CPU to throttle. A heat sink can help to control the core temperature, and therefore performance. This is especially useful if the Raspberry Pi is running inside a case. Airflow over the heat sink will make cooling more efficient.

When the core temperature is between 80°C and 85°C, the ARM cores will be throttled back. If the temperature exceeds 85°C, the ARM cores and the GPU will be throttled back.

For the Raspberry Pi 3 Model B+, the PCB technology has been changed to provide better heat dissipation and increased thermal mass. In addition, a soft temperature limit has been introduced, with the goal of maximising the time for which a device can "sprint" before reaching the hard limit at 85°C. When the soft limit is reached, the clock speed is reduced from 1.4GHz to 1.2GHz, and the operating voltage is reduced slightly. This reduces the rate of temperature increase: we trade a short period at 1.4GHz for a longer period at 1.2GHz. By default, the soft limit is 60°C. This can be changed via the temp_soft_limit setting in config.txt.

It is essential to keep the supply voltage above 4.8V for reliable performance. Note that the voltage from some USB chargers/power supplies can fall as low as 4.2V. This is because they are usually designed to charge a 3.7V LiPo battery, not to supply 5V to a computer.

To monitor the Raspberry Pi’s PSU voltage, you will need to use a multimeter to measure between the VCC and GND pins on the GPIO. More information is available in the power section of the documentation.

If the voltage drops below 4.63V (±5%), the ARM cores and the GPU will be throttled back, and a message indicating the low voltage state will be added to the kernel log.

The Raspberry Pi 5 PMIC has built in ADCs that allow the supply voltage to be measured. To view the current supply voltage, run the following command:

Most overclocking issues show up immediately, when the device fails to boot. If your device fails to boot due to an overclocking configuration change, use the following steps to return your device to a bootable state:

The [all] filter is the most basic filter. It resets all previously set filters and allows any settings listed below it to be applied to all hardware. It is usually a good idea to add an [all] filter at the end of groups of filtered settings to avoid unintentionally combining filters (see below).

The conditional model filters apply according to the following table.

These are particularly useful for defining different kernel, initramfs, and cmdline settings, as the Raspberry Pi 1 and Raspberry Pi 2 require different kernels. They can also be useful to define different overclocking settings, as the Raspberry Pi 1 and Raspberry Pi 2 have different default speeds. For example, to define separate initramfs images for each:

Remember to use the [all] filter at the end, so that any subsequent settings aren’t limited to Raspberry Pi 2 hardware only.

The [none] filter prevents any settings that follow from being applied to any hardware. Although there is nothing that you can’t do without [none], it can be a useful way to keep groups of unused settings in config.txt without having to comment out every line.

This filter succeeds if the tryboot reboot flag was set.

It is intended for use in autoboot.txt to select a different boot_partition in tryboot mode for fail-safe OS updates.

When switching between multiple monitors while using a single SD card in your Raspberry Pi, and where a blank config isn’t sufficient to automatically select the desired resolution for each one, this allows specific settings to be chosen based on the monitors' EDID names.

To view the EDID name of an attached monitor, you need to follow a few steps. Run the following command to see which output devices you have on your Raspberry Pi:

On a Raspberry Pi 4, this will print something like:

You then need to run edid-decode against each of these filenames, for example:

If there’s no monitor connected to that particular output device, it’ll tell you the EDID was empty; otherwise it will serve you lots of information about your monitor’s capabilities. You need to look for the lines specifying the Manufacturer and the Display Product Name. The "EDID name" is then <Manufacturer>-<Display Product Name>, with any spaces in either string replaced by underscores. For example, if your edid-decode output included:

The EDID name for this monitor would be DEL-DELL_U2422H.

You can then use this as a conditional-filter to specify settings that only apply when this particular monitor is connected:

These settings apply only at boot. The monitor must be connected at boot time, and the Raspberry Pi must be able to read its EDID information to find the correct name. Hotplugging a different monitor into the Raspberry Pi after boot will not select different settings.

On the Raspberry Pi 4, if both HDMI ports are in use, then the EDID filter will be checked against both of them, and configuration from all matching conditional filters will be applied.

Sometimes settings should only be applied to a single specific Raspberry Pi, even if you swap the SD card to a different one. Examples include licence keys and overclocking settings (although the licence keys already support SD card swapping in a different way). You can also use this to select different display settings, even if the EDID identification above is not possible, provided that you don’t swap monitors between your Raspberry Pis. For example, if your monitor doesn’t supply a usable EDID name, or if you are using composite output (from which EDID cannot be read).

To view the serial number of your Raspberry Pi, run the following command:

A 16-digit hex value will be displayed near the bottom of the output. Your Raspberry Pi’s serial number is the last eight hex-digits. For example, if you see:

The serial number is 12345678.

You can define settings that will only be applied to this specific Raspberry Pi:

You can also filter depending on the state of a GPIO. For example:

Filters of the same type replace each other, so [pi2] overrides [pi1], because it is not possible for both to be true at once.

Filters of different types can be combined by listing them one after the other, for example:

Use the [all] filter to reset all previous filters and avoid unintentionally combining different filter types.

decode_MPG2 is a licence key to allow hardware MPEG-2 decoding, e.g. decode_MPG2=0x12345678.

decode_WVC1 is a licence key to allow hardware VC-1 decoding, e.g. decode_WVC1=0x12345678.

If you have multiple Raspberry Pis and you’ve bought a codec licence for each of them, you can list up to eight licence keys in a single config.txt, for example decode_MPG2=0x12345678,0xabcdabcd,0x87654321. This enables you to swap the same SD card between the different Raspberry Pis without having to edit config.txt each time.

Composite video output can be found on each model of Raspberry Pi computer:

Setting awb_auto_is_greyworld to 1 allows libraries or applications that do not support the greyworld option internally to capture valid images and videos with NoIR cameras. It switches auto awb mode to use the greyworld algorithm. This should only be needed for NoIR cameras, or when the High Quality camera has had its IR filter removed.