The config.txt file

The config.txt file is read by the early-stage boot firmware, so it has a very simple file format. The format is 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 (previously 78) for entries - any characters past this limit will be ignored.

Here is an example file:

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

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 an hypothetical OS Update Service could use tryboot + autoboot.txt to perform an fail-safe OS upgrade.

Initial autoboot.txt

Installing the update

Committing or cancelling the update

Updated autoboot.txt

Notes * It’s not mandatory to reboot after updating autoboot.txt. However, the Update Service must be careful to avoid overwriting the current partition since autoboot.txt has already been modified to commit the last update.. * See also: Device-tree parameters.

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.

These options specify the firmware files transferred to the VideoCore GPU prior to booting.

start_file specifies the VideoCore firmware file to use. fixup_file specifies the file used to fix up memory locations used in the start_file to match the GPU memory split. Note that the start_file and the fixup_file are a matched pair - using unmatched files will stop the board from booting. This is an advanced option, so we advise that you use start_x and start_debug rather than this option.

These provide a shortcut to some alternative start_file and fixup_file settings, and are the recommended methods for selecting firmware configurations.

start_x=1 implies

On the Raspberry Pi 4, if the files start4x.elf and fixup4x.dat are present, these files will be used instead.

start_debug=1 implies

start_x=1 should be specified when using the camera module. Enabling the camera via raspi-config will set this automatically.

Set the disable_commandline_tags command to 1 to stop start.elf from filling in ATAGS (memory from 0x100) before launching the kernel.

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 to use when 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.

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 Pi 4s (Pi 4B, Pi 400, CM4 and CM4S), and 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.

Sets board-specific control bits.

armstub is the filename on the boot partition from which to load the ARM stub. The default ARM stub is stored in firmware and is selected automatically based on the Raspberry Pi model and various settings.

The stub is a small piece of ARM code that is run before the kernel. Its job is to set up low-level hardware like the interrupt controller before passing control to the kernel.

Set arm_peri_high to 1 to enable "High Peripheral" mode on the Raspberry Pi 4. It is set automatically if a suitable DTB is loaded.

kernel_address is the memory address to which the kernel image should be loaded. 32-bit kernels are loaded to address 0x8000 by default, and 64-bit kernels to address 0x200000. If kernel_old is set, kernels are loaded to the address 0x0.

Set kernel_old to 1 to load the kernel to the memory address 0x0.

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.

init_uart_baud is the initial UART baud rate. The default value is 115200.

init_uart_clock is the initial UART clock frequency. The default value is 48000000 (48MHz). Note that this clock only applies to UART0 (ttyAMA0 in Linux), and that the maximum baudrate for the UART is limited to 1/16th of the clock. The default UART on the Raspberry Pi 3 and Raspberry Pi Zero is UART1 (ttyS0 in Linux), and its clock is the core VPU clock - at least 250MHz.

The bootcode_delay command delays for a given number of seconds in bootcode.bin before loading start.elf: the default value is 0.

This is particularly useful to insert a delay before reading the EDID of the monitor, for example if the Raspberry Pi and monitor are powered from the same source, but the monitor takes longer to start up than the Raspberry Pi. Try setting this value if the display detection is wrong on initial boot, but is correct if you soft-reboot the Raspberry Pi without removing power from the monitor.

The boot_delay command instructs to wait for a given number of seconds in start.elf before loading the kernel: the default value is 1. The total delay in milliseconds is calculated as (1000 x boot_delay) + boot_delay_ms. This can be useful if your SD card needs a while to get ready before Linux is able to boot from it.

The boot_delay_ms command means wait for a given number of milliseconds in start.elf, together with boot_delay, before loading the kernel. The default value is 0.

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 doing this is useful if you need 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.

On the Raspberry Pi 4B, if this value is set to 0 then the interrupts will be routed to the ARM cores using the legacy interrupt controller, rather than via the GIC-400. The default value is 1.

enable_uart=1 (in conjunction with console=serial0 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 (stuck in front of) 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 - 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.

If set to non-zero, enables the logging of SHA256 hashes for loaded files (the kernel, initramfs, Device Tree .dtb file and overlays), as generated by the sha256sum utility. The logging output goes to the UART if enabled, and is also accessible via sudo vcdbg log msg. This option may be useful when debugging booting problems, but at the cost of potentially adding many seconds to the boot time. Defaults to 0 on all platforms.

Setting uart_2ndstage=1 causes the second-stage loader (bootcode.bin on devices prior to the Raspberry Pi 4, or the boot code in the EEPROM for Raspberry Pi 4 devices) and the main firmware (start*.elf) to output diagnostic information to UART0.

Be aware that output is likely to interfere with Bluetooth operation unless it is disabled (dtoverlay=disable-bt) or switched to the other UART (dtoverlay=miniuart-bt), and if the UART is accessed simultaneously to output from Linux then data loss can occur leading to corrupted output. This feature should only be required when trying to diagnose an early boot loading problem.

If upstream_kernel=1 is used, the firmware sets os_prefix to "upstream/", unless it has been explicitly set to something else, but like other os_prefix values it will be ignored if the required kernel and .dtb file can’t be found when using the prefix.

The firmware will also prefer upstream Linux names for DTBs (bcm2837-rpi-3-b.dtb instead of bcm2710-rpi-3-b.dtb, for example). If the upstream file isn’t found the firmware will load the downstream variant instead and automatically apply the "upstream" overlay to make some adjustments. Note that this process happens after the os_prefix has been finalised.

The gpio directive allows GPIO pins to be set to specific modes and values at boot time in a way that would previously have needed a custom dt-blob.bin file. Each line applies the same settings (or at least makes the same changes) to a set of pins, either a single pin (3), a range of pins (3-4), or a comma-separated list of either (3-4,6,8). The pin set is followed by an = and one or more comma-separated attributes from this list:

gpio settings are applied in order, so those appearing later override those appearing earlier.

Examples:

The gpio directive respects the "[…​]" section headers in config.txt, so it is possible to use different settings based on the model, serial number, and EDID.

GPIO changes made through this mechanism do not have any direct effect on the kernel — they don’t cause GPIO pins to be exported to the sysfs interface, and they can be overridden by pinctrl entries in the Device Tree as well as utilities like raspi-gpio.

Note also that there is a delay of a few seconds between power being applied and the changes taking effect — longer if booting over the network or from a USB mass storage device.

Setting enable_jtag_gpio=1 selects Alt4 mode for GPIO pins 22-27, and sets up some internal SoC connections, thus enabling the JTAG interface for the ARM CPU. It works on all models of Raspberry Pi.

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 that 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.

The GPU core, CPU, SDRAM and GPU each have their own PLLs and can have unrelated frequencies. The h264, v3d and ISP blocks share a PLL.

To view the Raspberry Pi’s current frequency in KHz, type: cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq. Divide the result by 1000 to find the value in MHz. Note that this frequency is the kernel requested frequency, and it is possible that any throttling (for example at high temperatures) may mean the CPU is actually running more slowly than reported. An instantaneous measurement of the actual ARM CPU frequency can be retrieved using the vcgencmd vcgencmd measure_clock arm. This is displayed in Hertz.

To view the Raspberry Pi’s temperature, type cat /sys/class/thermal/thermal_zone0/temp. Divide the result by 1000 to find the value in degrees Celsius. Alternatively, there is a vcgencmd, vcgencmd measure_temp that interrogates the GPU directly for its temperature.

Whilst hitting the temperature limit is not harmful to the SoC, it will cause CPU throttling. A heatsink 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 heatsink will make cooling more efficient.

With firmware from 12th September 2016 or later, when the core temperature is between 80’C and 85’C, a warning icon showing a red half-filled thermometer will be displayed, and the ARM cores will be throttled back. If the temperature exceeds 85’C, an icon showing a fully-filled thermometer will be displayed, and both 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, and this can be changed via the temp_soft_limit setting in config.txt.

See the page on warning icons for more details.

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 power.

If the voltage drops below 4.63V (+-5%), recent versions of the firmware will show a yellow lightning bolt symbol on the display to indicate a lack of power, and a message indicating the low voltage state will be added to the kernel log.

See the page on warning icons for more details.

Most overclocking issues show up immediately with a failure to boot. If this occurs, hold down the shift key during the next boot. This will temporarily disable all overclocking, allowing you to boot successfully and then edit your settings.

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 are applied 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, run the following command:

This will print something like this:

You can then specify settings that apply only to this monitor:

This forces 1920x1080 DVT mode for the specified monitor, without affecting any other monitors.

Note that these settings apply only at boot, so 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 will be checked against both of them, and subsequent configuration applied only to the first matching device. You can determine the EDID names for both ports by first running tvservice -l in a terminal window to list all attached devices and then using the returned numerical IDs in tvservice -v <id> -n to find the EDID name for a specific display ID.

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 (for which EDID cannot be read).

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

The serial will be shown as a 16-digit hex value at the bottom. For example, if you see:

then 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

The Raspberry Pi 4 has two HDMI ports, and for many config.txt commands related to HDMI, it is necessary to specify which HDMI port is being referred to. The HDMI conditional filters subsequent HDMI configurations to the specific port.

An alternative variable:index syntax is available on all port-specific HDMI commands. You could use the following, which is the same as the previous 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 simply 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.

Specifies how much memory, in megabytes, to reserve for the exclusive use of the GPU: the remaining memory is allocated to the ARM CPU for use by the OS. For Raspberry Pis with less than 1GB of memory, the default is 64; for Raspberry Pis with 1GB or more of memory the default is 76.

To ensure the best performance of Linux, you should set gpu_mem to the lowest possible value. If a particular graphics feature is not working correctly, try increasing the value of gpu_mem, being mindful of the recommended maximums shown below.

On the Raspberry Pi 4 the 3D component of the GPU has its own memory management unit (MMU), and does not use memory from the gpu_mem allocation. Instead memory is allocated dynamically within Linux. This allows a smaller value to be specified for gpu_mem on the Raspberry Pi 4, compared to previous models.

On legacy kernels, the memory allocated to the GPU is used for display, 3D, Codec and camera purposes as well as some basic firmware housekeeping. The maximums specified below assume you are using all these features. If you are not, then smaller values of gpu_mem should be used.

The recommended maximum values are as follows:

It is possible to set gpu_mem to larger values, however this should be avoided since it can cause problems, such as preventing Linux from booting. The minimum value is 16, however this disables certain GPU features.

You can also use gpu_mem_256, gpu_mem_512, and gpu_mem_1024 to allow swapping the same SD card between Raspberry Pis with different amounts of RAM without having to edit config.txt each time:

The gpu_mem_256 command sets the GPU memory in megabytes for Raspberry Pis with 256MB of memory. (It is ignored if memory size is not 256MB). This overrides gpu_mem.

The gpu_mem_512 command sets the GPU memory in megabytes for Raspberry Pis with 512MB of memory. (It is ignored if memory size is not 512MB). This overrides gpu_mem.

The gpu_mem_1024 command sets the GPU memory in megabytes for Raspberry Pis with 1GB or more of memory. (It is ignored if memory size is smaller than 1GB). This overrides gpu_mem.

This parameter can be used to force a Raspberry Pi to limit its memory capacity: specify the total amount of RAM, in megabytes, you wish the Raspberry Pi to use. For example, to make a 4GB Raspberry Pi 4B behave as though it were a 1GB model, use the following:

This value will be clamped between a minimum of 128MB, and a maximum of the total memory installed on the board.

Setting this to 1 disables the CPU’s access to the GPU’s L2 cache and requires a corresponding L2 disabled kernel. Default value on BCM2835 is 0. On BCM2836, BCM2837, and BCM2711, the ARMs have their own L2 cache and therefore the default is 1. The standard Raspberry Pi kernel.img and kernel7.img builds reflect this difference in cache setting.

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.

In order to support dual 4k displays, the Raspberry Pi 4 has updated video hardware, which imposes minor restrictions on the modes supported.

Your HDMI monitor may only support a limited set of formats. To find out which formats are supported, use the following method:

The edid.dat should also be provided when troubleshooting problems with the default HDMI mode.

If your monitor requires a mode that is not in one of the tables above, then it’s possible to define a custom CVT mode for it instead:

Fields at the end can be omitted to use the default values.

Note that this simply creates the mode (group 2 mode 87). In order to make the Raspberry Pi use this by default, you must add some additional settings. For example, the following selects an 800 × 480 resolution and enables audio drive:

This may not work if your monitor does not support standard CVT timings.

The table below describes where composite video output can be found on each model of Raspberry Pi computer:

Setting disable_camera_led to 1 prevents the red camera LED from turning on when recording video or taking a still picture. This is useful for preventing reflections when the camera is facing a window, for example.

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.

The warning symbols can be disabled using this option, although this is not advised.

avoid_warnings=1 disables the warning overlays. avoid_warnings=2 disables the warning overlays, but additionally allows turbo mode even when low-voltage is present.

Sets the VideoCore logging level. The value is a VideoCore-specific bitmask.

Originally certain models of Raspberry Pi limited the USB ports to a maximum of 600mA. Setting max_usb_current=1 changed this default to 1200mA. However, all firmware now has this flag set by default, so it is no longer necessary to use this option.