Raspberry Pi Headless Setup

A “headless” setup boots a Raspberry Pi for the first time without a monitor or keyboard — useful when the Pi is destined for a remote location, mounted inside a project, or you simply don’t have a spare display. This guide covers both the modern Bookworm+ method and the older Bullseye-and-earlier method.

Modern method (Bookworm and newer)

Since Raspberry Pi OS Bookworm, released 10 October 2023, the official way to do headless setup is via the Raspberry Pi Imager’s OS Customisation dialog. The old trick of dropping an ssh file and wpa_supplicant.conf onto the boot partition no longer works — Bookworm uses NetworkManager and ignores those files.

Step 1 — Pick OS and storage

Open Raspberry Pi Imager and pick your device, OS, and SD card. See Write Raspberry Pi OS to an SD Card for the basic flow.

Step 2 — Edit settings before writing

When prompted, click Edit Settings (or press Ctrl+Shift+X on older Imager versions).

On the General tab, configure:

  • Hostname — e.g. mypi. The Pi will be reachable as mypi.local via mDNS.
  • Username + password — Bookworm dropped the default pi / raspberry account, so this is required.
  • WiFi SSID, password, and country — so the Pi auto-joins your network on first boot.
  • Locale, timezone, keyboard layout — region defaults.

On the Services tab, enable SSH:

  • Use password authentication — simplest, uses the username/password from above.
  • Allow public-key authentication only — more secure; paste the contents of your ~/.ssh/id_*.pub.

Click Save, confirm the write, and let Imager finish.

Step 3 — First boot

Insert the SD card into your Pi and connect power. The first boot takes 1–3 minutes — partition expansion, applying the firstrun script, joining WiFi, and a restart.

Step 4 — Find the Pi on the network

Easiest: use the hostname directly. If you set mypi:

ssh youruser@mypi.local

.local resolution uses mDNS (Avahi / Bonjour). It works out of the box on macOS and most Linux. Recent Windows builds support it too; if not, install Bonjour Print Services.

If .local doesn’t resolve, find the IP address by:

  • Router admin page — list of connected DHCP clients.
  • nmap ping sweep:
  nmap -sn 192.168.1.0/24
  • arp -a on your computer after pinging the broadcast address.

Then connect by IP:

ssh youruser@192.168.1.42

Older method (Bullseye and earlier)

For Raspberry Pi OS Bullseye (Debian 11) and earlier — Buster, Stretch, Jessie — the classic “drop two files on the boot partition” trick still works.

Step 1 — Flash the image

Use Raspberry Pi Imager (or dd) to write a Bullseye-or-earlier image to the SD card. Don’t eject yet — re-insert if your computer auto-ejects after writing.

Step 2 — Add an empty ssh file

In the boot partition (the FAT32 partition Windows can read), create an empty file named exactly ssh — no extension. This signals first-boot to enable the SSH server.

On Windows, the easiest way is View → Show file extensions, create a new text document, and rename it from New Text Document.txt to ssh (confirming the extension change).

Step 3 — Add wpa_supplicant.conf

In the same boot partition, create a file named wpa_supplicant.conf containing:

country=MY
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="Your-SSID"
    psk="Your-Password"
}

Replace country=MY with your ISO 3166-1 alpha-2 country code. See Raspberry Pi WiFi Setup for hidden SSID, hashed PSK, multiple networks, and other variants.

Step 4 — Boot and connect

Eject, insert into the Pi, power on. On first boot the Pi moves both files into place and joins the WiFi. Default credentials on Bullseye and earlier are pi / raspberry:

ssh pi@raspberrypi.local

Change the password immediately with passwd.

Troubleshooting

Pi doesn’t appear on the network

  • Check the WiFi country code is correct — wrong code blocks 5GHz channels and may block 2.4GHz too in some regions.
  • Confirm the Pi is in WiFi range.
  • For Bookworm, double-check that OS Customisation values were saved before writing.
  • For Bullseye, confirm wpa_supplicant.conf is in the boot partition (not the root partition).

mypi.local doesn’t resolve

  • Some Windows installs lack mDNS — use the IP from the router admin page instead.
  • Some corporate networks block mDNS broadcasts — same workaround.

ssh: connection refused

  • For Bookworm, confirm SSH was enabled in OS Customisation → Services.
  • For Bullseye, confirm an ssh file (no extension, empty) is in the boot partition.