Foundation

Raspberry Pi
Documentation

Computers

Accessories

Microcontrollers

Services

Pico C SDK

The conEg.txt Ele

What is config.txt?
Edit this on GitHub

The Raspberry Pi uses a con2guration 2le instead of the

BIOS you would expect to 2nd on a conventional PC. The
system con2guration parameters, which would
traditionally be edited and stored using a BIOS, are stored
instead in an optional text 2le named config.txt. This
is read by the GPU before the ARM CPU and Linux are
initialised. It must therefore be located on the 2rst (boot)
partition of your SD card, alongside bootcode.bin and
start.elf. This 2le is normally accessible as
/boot/config.txt from Linux, and must be edited as
the root user. From Windows or OS X it is visible as a 2le
in the only accessible part of the card. If you need to
apply some of the con2g settings below, but you don’t
have a config.txt on your boot partition yet, simply
create it as a new text 2le.

Any changes will only take effect after you have rebooted
your Raspberry Pi. After Linux has booted, you can view
the current active settings using the following
commands:

vcgencmd get_config <config>: this displays a

speci2c con2g value, e.g. vcgencmd get_config
arm_freq.

vcgencmd get_config int: this lists all the

integer con2g options that are set (non-zero).

vcgencmd get_config str: this lists all the

string con2g options that are set (non-null).

NOTE

There are some con2g settings that cannot be

retrieved using vcgencmd.

File Format
The config.txt 2le is read by the early-stage boot
2rmware, so it has a very simple 2le 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 con2g 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 2le:

# Enable audio (loads snd_bcm2835)

dtparam=audio=on

# Automatically load overlays for detected cameras

camera_auto_detect=1

# Automatically load overlays for detected DSI displays

display_auto_detect=1

# Enable DRM VC4 V3D driver

dtoverlay=vc4-kms-v3d
max_framebuffers=2

# Disable compensation for displays with overscan

disable_overscan=1

Advanced Features

include

Causes the content of the speci2ed 2le to be inserted into

the current 2le.

For example, adding the line include

extraconfig.txt to config.txt will include the
content of extraconfig.txt 2le in the config.txt 2le.

Include directives are not supported by bootcode.bin or

the EEPROM bootloader

Conditional Filtering

Conditional 2lters are covered in the conditionals section.

autoboot.txt
Edit this on GitHub

autoboot.txt is an optional con2guration 2le that can

be used to specify the boot_partition number. This is
sometimes used with NOOBS to bypass the boot menu
selection and boot a speci2c partition.

This can also be used in conjunction with the tryboot

feature to implement A/B booting for OS upgrades.

autoboot.txt is limited to 512 bytes and supports the

[all], [none] and [tryboot] conditional 2lters.

See also TRYBOOT boot ^ow.

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

The [tryboot] Elter

This 2lter passes if the system was booted with the
tryboot ^ag set.

sudo reboot "0 tryboot"

tryboot_a_b
Set this property to 1 to load the normal config.txt and
boot.img 2les instead of tryboot.txt and
tryboot.img when the tryboot ^ag is set. This enables
the tryboot switch to be made at the partition level
rather than the 2le-level without having to modify
con2guration 2les in the A/B partitions.

Example update Iow for A/B

booting
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

[all]
tryboot_a_b=1
boot_partition=2
[tryboot]
boot_partition=3

Installing the update

System is powered on and boots to partition 2 by

default.

An Update Service downloads the next version

of the OS to partition 3.

The update is tested by rebooting to tryboot

mode reboot "0 tryboot" where 0 means the
default partition.

Committing or cancelling the update

System boots from partition 3 because the

[tryboot] 2lter evaluates to true in tryboot
mode.

If tryboot is active (/proc/device-

tree/chosen/bootloader/tryboot == 1)

If the current boot partition (/proc/device-

tree/chosen/bootloader/partition)
matches the boot_partition in the
[tryboot] section of autoboot.txt

The Update Service validates the

system to verify that the update was
successful.

If the update was successful

Replace autoboot.txt
swapping the boot_partition
con2guration.

Normal reboot - partition 3 is

now the default boot partition.

Else

Update Service marks the

update as failed e.g. it removes
the update 2les.

Normal reboot - partition 2 is still

the default boot partition
because the tryboot ^ag is
automatically cleared.

End if

End If

End If

Updated autoboot.txt

[all]
tryboot_a_b=1
boot_partition=3
[tryboot]
boot_partition=2

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 modi2ed to commit the
last update.. * See also: Device-tree parameters.

Common Options
Edit this on GitHub

Common Display Options

disable_overscan

The default value for disable_overscan is 0 which

gives default values of overscan for the left, right, top, and
bottom edges of 48 for HD CEA modes, 32 for SD CEA
modes, and 0 for DMT modes.

Set disable_overscan to 1 to disable the default values

of overscan that are set by the 2rmware.

hdmi_enable_4kp60 (Raspberry Pi 4 Only)

By default, when connected to a 4K monitor, the

Raspberry Pi 4B, 400 and CM4 will select a 30Hz refresh
rate. Use this option to allow selection of 60Hz refresh
rates.

IMPORTANT

It is not possible to output 4Kp60 on both micro HDMI

ports simultaneously.

WARNING

Setting hdmi_enable_4kp60 will increase power

consumption and the temperature of your Raspberry
Pi.

Common Hardware ConEguration

Options

camera_auto_detect

With this setting enabled (set to 1), the 2rmware will

automatically load overlays for cameras that it
recognises.

IMPORTANT

New Raspberry Pi OS images from Bullseye onwards

come with this setting by default.

display_auto_detect

With this setting enabled (set to 1), the 2rmware will

automatically load overlays for displays that it recognises.

IMPORTANT

New Raspberry Pi OS images from Bullseye onwards

come with this setting by default.

dtoverlay

The dtoverlay option requests the 2rmware to load a

named Device Tree overlay - a con2guration 2le that can
enable kernel support for built-in and external hardware.
For example, dtoverlay=vc4-kms-v3d loads an overlay
that enables the kernel graphics driver.

As a special case, if called with no value - dtoverlay= - it

marks the end of a list of overlay parameters. If used
before any other dtoverlay or dtparam setting it
prevents the loading of any HAT overlay.

For more details, see DTBs, overlays and con2g.txt.

dtparam

Device Tree con2guration 2les for Raspberry Pis support

a number of parameters for such things as enabling I2C
and SPI interfaces. Many DT overlays are con2gurable via
the use of parameters. Both types of parameters can be
supplied using the dtparam setting. In addition, overlay
parameters can be appended to the dtoverlay option,
separated by commas, but beware the line length limit -
previously 78 characters, now 98 characters.

For more details, see DTBs, overlays and con2g.txt.

arm_boost (Raspberry Pi 4 Only)

All Raspberry Pi 400s and newer revisions of the

Raspberry Pi 4B are equipped with a second switch-mode
power supply for the SoC voltage rail, and this allows the
default turbo-mode clock to be increased from 1.5GHz to
1.8GHz. This change should be safe for all such boards,
but to avoid unrequested changes for existing
installations this change must be accepted by setting
arm_boost=1.

IMPORTANT

New Raspberry Pi OS images from Bullseye onwards

come with this setting by default.

Onboard Analogue Audio

(3.5mm Jack)
Edit this on GitHub

The onboard audio output uses con2g options to change

the way the analogue audio is driven, and whether some
2rmware features are enabled or not.

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

NOTE

This option uses more GPU compute resources and

can interfere with some use cases.

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

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

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

Boot Options
Edit this on GitHub

start_file, fixup_file
These options specify the 2rmware 2les transferred to the
VideoCore GPU prior to booting.

start_file speci2es the VideoCore 2rmware 2le to use.

fixup_file speci2es the 2le used to 2x 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 2les
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.

start_x, start_debug
These provide a shortcut to some alternative
start_file and fixup_file settings, and are the
recommended methods for selecting 2rmware
con2gurations.

start_x=1 implies

start_file=start_x.elf
fixup_file=fixup_x.dat

On the Raspberry Pi 4, if the 2les start4x.elf and

fixup4x.dat are present, these 2les will be used
instead.

start_debug=1 implies

start_file=start_db.elf
fixup_file=fixup_db.dat

start_x=1 should be speci2ed when using the camera

module. Enabling the camera via raspi-config will set
this automatically.

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

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

kernel
kernel is the alternative 2lename 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.

arm_64bit
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 2rmware will choose an appropriate

kernel (e.g. kernel8.img), unless there is an explicit
kernel option de2ned, 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.

NOTE

64-bit kernels may be uncompressed image 2les or a

gzip archive of an image (which can still be called
kernel8.img; the bootloader will recognize the archive
from the signature bytes at the beginning).

NOTE

The 64-bit kernel will only work on the Raspberry Pi 3,

3+, 4, 400, Zero 2 W and 2B rev 1.2, and Raspberry Pi
Compute Modules 3, 3+ and 4.

arm_control
WARNING

This setting is DEPRECATED, use arm_64bit instead

to enable 64-bit kernels.

Sets board-speci2c control bits.

armstub
armstub is the 2lename on the boot partition from which
to load the ARM stub. The default ARM stub is stored in
2rmware 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.

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

NOTE

Enabling "High Peripheral" mode without a compatible

device tree will make your system fail to boot.
Currently ARM stub support is missing, so you will
also need to load a suitable 2le using armstub.

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

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

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

NOTE

Newer 2rmware supports the loading of multiple

ramfs 2les. You should separate the multiple 2le
names with commas, taking care not to exceed the
80-character line length limit. All the loaded 2les are
concatenated in memory and treated as a single
ramfs blob. More information is available on the
forums.

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

initramfs
The initramfs command speci2es both the ramfs
2lename 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 2rmwares
allow the loading of multiple 2les by comma-separating
their names.

NOTE

This option uses different syntax from all the other

options, and you should not use a = character here.

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

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

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

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

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

disable_poe_fan
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