Configure a Headless Raspberry Pi Before First Boot

Configure a headless Raspberry Pi before first boot using Raspberry Pi Imager or manual SD card edits. No monitor, no keyboard required.

The Pi is already mounted inside the enclosure. The enclosure is already bolted to the wall. There is no HDMI port accessible, no USB keyboard handy, and the device needs to be on the network in twenty minutes. This is the moment most people realize they should have configured the Pi before it left the bench.

Headless configuration, done before first boot, means the Pi connects to the network and accepts SSH logins the moment power is applied. No monitor. No keyboard. No guesswork. This guide covers exactly how to do it, for both Raspberry Pi OS Bookworm (the current release) and older Bullseye images, since the method changed significantly between the two.

Two Configuration Paths

There are two ways to write headless configuration to an SD card before first boot. The first is through Raspberry Pi Imager, which handles everything inside a GUI during the write process. The second is by editing files directly on the boot partition after writing the image. Both work. Imager is faster for a single device. Direct file editing is easier to script for a fleet.

Using Raspberry Pi Imager

Download and install [Raspberry Pi Imager](https://www.raspberrypi.com/software/) from the official site. Insert the SD card into a card reader connected to your workstation.

1. Open Imager and choose your OS. Raspberry Pi OS Lite (64-bit) is the correct choice for headless deployments. It has no desktop environment.
2. Choose your storage device. Double-check the target. Imager will overwrite whatever is selected.
3. Click the gear icon (or press Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS) to open the Advanced Options panel before writing.
4. Set hostname, enable SSH, choose 'Use password authentication' or paste a public key, and configure your Wi-Fi credentials if needed.
5. Click Save, then Write. Imager embeds the configuration directly into the image.

In Raspberry Pi OS Bookworm (released late 2023), SSH is disabled by default and the 'ssh' touch file is no longer supported. The only supported methods are Imager's Advanced Options or the firstrun.sh approach described below. Do not rely on the old empty 'ssh' file if you are writing a Bookworm image.

Manual Configuration on the Boot Partition

After writing the image with Imager (without using Advanced Options) or any other tool, the boot partition is visible as a small FAT32 volume on any OS. On macOS and Windows it appears automatically. On Linux it mounts at a path like /media/username/bootfs.

Raspberry Pi OS Bookworm uses a file called **firstrun.sh** placed in the root of the boot partition. Imager generates this file automatically when you use Advanced Options. If you are scripting image preparation, you can generate this file yourself. The structure is a shell script that runs once on first boot and then deletes itself. It writes configuration to /etc, sets the hostname, creates the user, and enables SSH.

A minimal firstrun.sh that enables SSH and creates a user looks like this:

• Set hostname: `echo myhostname > /etc/hostname`
• Create user with hashed password using `openssl passwd -6 yourpassword` and write the result into /etc/shadow or use the userconf-pi service format.
• Enable SSH: `systemctl enable ssh`
• Add your public key to /home/username/.ssh/authorized_keys with correct permissions (chmod 700 on .ssh, chmod 600 on authorized_keys).
• The script must be marked executable and referenced from cmdline.txt as `systemd.run=/boot/firstrun.sh systemd.run_success_action=reboot`.

For most single-device setups, Imager's Advanced Options produce a correct firstrun.sh with no manual work. Manual firstrun.sh editing is worth learning only if you are imaging devices programmatically.

Wi-Fi Configuration

On Bullseye and earlier, Wi-Fi was configured by placing a file named **wpa_supplicant.conf** in the root of the boot partition. On first boot, the OS copied it to /etc/wpa_supplicant/. That file method is not supported in Bookworm.

On Bookworm, Wi-Fi credentials are written into **/etc/NetworkManager/system-connections/** as a .nmconnection file. Imager generates this correctly when you enter SSID and password in Advanced Options. If writing manually, the file format is a standard NetworkManager keyfile with sections for [connection], [wifi], and [wifi-security].

For wired Ethernet deployments, none of this is necessary. Plug in the cable and the Pi will obtain an IP via DHCP without any pre-configuration. Wired is simpler and more reliable for fixed installations.

Finding the Pi on the Network

Once the Pi boots, you need its IP address to connect. Three practical approaches:

• Check your router's DHCP client table. Look for the hostname you set.
• Use mDNS: `ping myhostname.local` from another machine on the same network. This works on macOS without any setup. On Linux, install avahi-daemon. On Windows 10 and later it works natively.
• Use a network scanner like `nmap -sn 192.168.1.0/24` to list all active hosts on the subnet.

Once you have the IP, connect with `ssh username@192.168.1.x` or `ssh username@myhostname.local`. If you used a public key during image setup, no password prompt appears. For more detail on SSH connection options and key management, see [SSH for Raspberry Pi: Headless Access in the Field](ssh-raspberry-pi-headless-field-access).

Post-Boot Configuration Checklist

First boot configuration gets the Pi onto the network. A small amount of additional work makes it suitable for unattended operation.

• Run `sudo apt update && sudo apt full-upgrade` and reboot.
• Set the correct timezone: `sudo timedatectl set-timezone Region/City`.
• Expand the filesystem if not done automatically: `sudo raspi-config --expand-rootfs`.
• Disable password authentication for SSH once your key is confirmed working. In /etc/ssh/sshd_config, set `PasswordAuthentication no`.
• Configure unattended-upgrades if the device will sit in the field for extended periods.
• Test a full power cycle. Confirm the Pi reconnects and SSH is available without intervention.

For devices that will be physically inaccessible after deployment, remote access planning matters before the unit ships. [How to SSH to Raspberry Pi Without a Monitor](how-to-ssh-raspberry-pi-no-monitor) covers the access patterns in more depth, and [Raspberry Pi SSH Access for Unattended Remote Nodes](raspberry-pi-ssh-unattended-remote-nodes) addresses what happens when the network environment at the deployment site is not fully under your control.

For Production Deployments

The process above works reliably for development and small-scale deployments on standard Raspberry Pi boards. For production infrastructure, particularly devices that run continuously in locations without regular physical access, the hardware platform matters as much as the software configuration.

When moving to the Compute Module 4 or CM5 for production work, the carrier board determines whether headless operation is practical at scale. Poepi is a CM4/CM5 carrier board designed specifically for unattended headless deployments, delivering both power and network over a single Ethernet cable so there is no separate power supply to fail or disconnect.

Regardless of hardware, the core principle is the same: configuration embedded before first boot is more reliable than any first-run manual step. Devices that boot correctly the first time, recover from power loss without intervention, and accept SSH connections from a known key are the ones that stay in service.