Raspberry Pi: What is cmdline.txt and how to use it?

When you create a new SD card for your Raspberry Pi, it not only includes the system files for Raspberry Pi OS (or any other distribution), but also some less known configuration files, like config.txt and cmdline.txt. In this article, I’ll introduce the cmdline.txt. In most cases, you don’t need to edit it, but it can be useful to know a little more about it.

The cmdline.txt file is a configuration file, located in the boot partition of the SD card on Raspberry Pi, and used to pass additional parameters to the Linux Kernel for the system boot.

I’ll start by giving you more details about the theory, then explain the different parameters that can be set, and in which cases it might be useful for you.

If you’re looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Introduction to the cmdline.txt file on Raspberry Pi

Goal

The Linux kernel is the main element of any Linux system. It’s a low-level piece of software, that creates the interface between the hardware and the operating system. On boot, it’s started before the main system, the operating system depends on it to work.

Raspberry Pi OS is using cmdline.txt to set options that the kernel will use on boot. For example, this file may include some hardware settings, like the storage drive ID, so the kernel knows what to do on startup.

A cmdline.txt file exists with most Linux systems, it’s not only for Raspberry Pi OS, but I’ll focus on the example of Raspberry Pi OS in this article.

If you need an introduction (or refresher) about the Linux kernel, this video is an excellent starting point:

https://www.youtube.com/watch?v=mycVSMyShk8

Location

The cmdline.txt is created under the boot partition (/boot) when a new system is flashed on a Raspberry Pi SD card.

It’s the partition formatted in FAT on the SD card, so it can be read from any operating system (even on Windows):

Related article: The Raspberry Pi file system explained.

Editing the cmdline file

The cmdline.txt file, generated on the SD card during the installation, can be edited from any computer or operating system.

If you use Windows to flash the SD card, you may need to unplug/plug the SD card again to mount it once Raspberry Pi Imager or Etcher is complete (these tools auto-eject the SD card when they are done). But it’s located on the partition you can read and edit, so it’s not complicated.

On Linux, the file location will vary depending on the mounting point, but it should be mounted automatically on most systems, you’ll find the boot partition in your file explorer (just make sure it’s the one on the SD card, and not the one in /boot, that is for your computer).

You can also edit the file on the SD card directly from your Raspberry Pi. In this case, that’s the file under /boot that you need to open.
Don’t forget to use sudo if you plan to edit it, for example:
sudo nano /boot/cmdline.txt

Any text editor can be used to open and edit this file (see my favorites here).
All the parameters are on one line, so there is no need to use anything fancy for this task.

Are you a bit lost in the Linux command line? Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

What is in the cmdline.txt on Raspberry Pi?

On a Raspberry Pi, the cmdline.txt is used to pass parameters to the Linux kernel for the boot process. It’s mainly used to configure the actions that will happen on the first boot or specify the operating system partition.

The default configuration of cmdline.txt

Let’s start by taking a looking at the default file’s content.

With Raspberry Pi OS, the cmdline.txt is different on the first boot and once the installation is completed.

Before the first boot

The initial cmdline.txt file includes additional parameters, telling the kernel the tasks to start on the first boot. When you just flash the SD card with Raspberry Pi OS, the file looks like this:

console=serial0,115200 console=tty1 root=PARTUUID=1d124286-02 rootfstype=ext4 fsck.repair=yes rootwait quiet init=/usr/lib/raspberrypi-sys-mods/firstboot splash plymouth.ignore-serial-consoles systemd.run=/boot/firstrun.sh systemd.run_success_action=reboot systemd.unit=kernel-command-line.target

Everything is on one line, so it’s not easy to read, but it’s just several arguments one after another.
I’ll explain what they mean later, but you can identify a syntax pattern like this:
argument1=value1 argument2=value2 argument3=value3 ...

After the first boot

When Raspberry Pi OS has started completely at least once, with the initialization tasks done, the fille’s content will be shorter, with something like this:

console=serial0,115200 console=tty1 root=PARTUUID=7a905b6b-02 rootfstype=ext4 fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles

You can notice that most parameters related to the first boot are no longer present.

If after reading this article you edit your cmdline.txt file and make some mistakes making your Raspberry Pi unstable or unwilling to boot, you can take this as an example to restore your file.
You’ll just need to update the “PARTUUID” variable with your system partition ID.

So, what are all these parameters, and when can it be useful to edit this file?
Let’s start by explaining the ones we have in the last example, which are the main parameters for the Linux kernel.

Main parameters of cmdline.txt

• console: It’s basically information about the display interface.
  The kernel generally starts on tty0 or tty1. On Raspberry Pi OS, it’s tty1.
  You shouldn’t need to edit this. Same thing for the serial port, which most people don’t need.
  
• root: As you may have guessed, it contains the partition ID for the operating system.
  It’s especially useful to have it there for the “rootwait” argument mentioned later.
  You can use the “fdisk” command (explained here) to see all your partitions IDs.
  
• rootfstype: The file format used for the main partition. With most Linux distributions, it will be EXT4.
  
• rootwait: We tell the kernel to wait for the system partition to be accessible before starting the operating system. As we work with an SD card, it may take more time than on a traditional computer.
  
• splash: Whether the splash image should be displayed on boot or not (the Raspberry Pi logo).
  If you remove this option, it will only show a black screen instead.
  
• plymouth.ignore-serial-consoles: Tell Plymouth to not display anything on the serial console output. Plymouth is the display manager during the boot process.

Additional options in cmdline.txt

On the file used for the first boot, there are a few other parameters:

• systemd.run and systemd.run_success_action: Used by the Raspberry Pi Foundation for the additional tasks to run on the first boot.
  Basically, they run a script (firstrun.sh) that will do all the tasks you set in the advanced options with Raspberry Pi Imager.
  If you check the script before the first boot, it looks like:
  
  In this example, it will change the default hostname and enable SSH.
  
• init: I’m not sure 100% for this one, but I guess it’s another script created by the Raspberry Pi developers. I would say it’s probably to run the initial tasks before the first boot, like resizing the system partition.
  It’s also possible to use this parameter for other things, like booting in single mode when you have lost your password (I give more details here).
  

Here are all the options you can find for Raspberry Pi OS by default, so I hope I have clarified them. But there are many other things you can do with this file, and additional questions you might have.
I’ll try to answer the most common uses of this file in a Q&A format.

If you have anything else you want to know about this file, please ask them inside the community forums.

FAQ

Can you set a static IP address via the cmdline.txt file?

The additional parameter “ip” can be added to the cmdline.txt file to set a static IP address on the first boot.

An example would be to add something like that at the end of the file (same line):
ip=192.168.222.50::192.168.222.1:255.255.255.0:rpi:eth0:off

In this example, my Raspberry Pi will boot with the IP address 192.168.222.50, using 192.168.222.1 as the gateway, and the traditional mask (/24).

It worked fine during my tests, but I don’t recommend using it. Try to use your DHCP on the first boot instead (or start without any network) and then follow this other tutorial to set a static IP address on the Raspberry Pi.

If you do this in the cmdline.txt it will only work on the first boot, and will most likely create conflicts with the dhcpcd service if a DHCP server is active on your network (causing the Raspberry Pi to have two IPs assigned, and switching from one to another constantly).

Can you use cmdline.txt to enable SSH on boot?

The easiest way to enable SSH on boot on Raspberry Pi is to create an empty file, named “ssh” in the boot partition of the SD card. There is no need to use cmdline.txt for this.

You can read this other article if you want to learn more about it: Install your Raspberry Pi Zero without Keyboard and Monitor.

Would it be possible to configure network boot via cmdline.txt?

The latest firmware versions of Raspberry Pi allow you to use network boot directly (as explained here), so there is no need to edit the cmdline.txt file to configure this.

I have seen some old tutorials doing it by adding additional parameters, but I don’t see the point to do this currently (maybe I’m missing something, please let me know).

Why do I get an error “/boot/cmdline.txt is unwritable”?

The cmdline.txt is not editable by the default user on Raspberry Pi, administrator privileges are required, so you need to use sudo to edit its content:
sudo nano /boot/cmdline.txt

Learn more about the administrator privileges here, and you can also check my guide for Nano if you are not used to it.

Is the cdmline.txt file different to other distributions?

Most Linux distributions have a cmdline.txt, with similar content, to pass optional parameters to the kernel. They will use different options and values, but the format is similar.

For example, here is the default cmdline.txt file on Ubuntu:
elevator=deadline net.ifnames=0 console=serial0,115200 dwc_otg.lpm_enable=0 console=tty1 root=LABEL=writable rootfstype=ext4 rootwait fixrtc quiet splash

Some of these options are familiar (console, root, splash, etc.) but there are some additional ones based on the Ubuntu distribution.

Is there complete documentation on how to use this file?

Unfortunately, I didn’t find any good reference documentation about this cmdline.txt file. That’s why some of my answers here may look like “guesses” more than formal explanations.

The Raspberry Pi Foundation has nothing about it, and even for PC, it’s hard to find something complete.
If you need more details, I would try to search the options for Debian (it should be very similar to Raspberry Pi OS), or ask your questions on the official forums of the major distributions.

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.