Headless Raspberry Pi 4 Setup on Ubuntu 24: What the Old Guides Get Wrong

30 Apr 2026

The problem with most Raspberry Pi guides

Search for “headless Raspberry Pi setup” and you’ll find dozens of guides. Most of them are wrong — not because the authors made mistakes, but because Raspberry Pi OS changed significantly in 2024 with the Bookworm release, and those guides haven’t caught up.

I followed one of those old guides and hit a wall immediately: no default pi user, WiFi config that silently did nothing, and SSH that wouldn’t connect despite the ssh file being present. After working through it hands-on, here’s what actually works in 2026.

What changed in Bookworm (and why old guides fail)

Old method (pre-2024) New method (Bookworm)
Default user pi with password raspberry No default user — must create manually
wpa_supplicant.conf for WiFi nmcli from inside Pi, or network-config cloud-init
ssh file in boot = SSH enabled Still works BUT requires userconf.txt too
rpi-imager handled everything rpi-imager snap on Ubuntu has bugs — don't trust it fully

The biggest trap: even if rpi-imager reports success, the boot partition may be missing userconf.txt. Without it, there’s no user account to SSH into, so the connection is refused regardless of whether SSH is enabled.

Hardware needed

The setup, step by step

Install rpi-imager

The snap package is the easiest way to get rpi-imager on Ubuntu 24:

sudo snap install rpi-imager

Flash the SD card

Insert your microSD card, then open rpi-imager:

rpi-imager

Select Raspberry Pi OS (64-bit), choose your SD card, then click the gear icon ⚙️ and fill in:

Hit Write — but don’t trust it blindly. The snap version of rpi-imager on Ubuntu has been known to write the image without applying all the custom config. Always verify manually.

Verify (and fix) the boot partition

After writing, the SD card mounts automatically. Check that both critical files exist:

# Check SSH file exists
ls /media/$USER/bootfs/ssh

# Check userconf.txt exists and has correct format
cat /media/$USER/bootfs/userconf.txt

If the ssh file is missing, create it:

sudo touch /media/$USER/bootfs/ssh

If userconf.txt is missing or malformed, you need to create it with a properly hashed password. Generate the hash first:

echo 'yourpassword' | openssl passwd -6 -stdin

Then write the file — it must be username:hashedpassword on a single line with no extra whitespace:

sudo nano /media/$USER/bootfs/userconf.txt
# Type: yourusername:$6$hash...
# Ctrl+O, Enter, Ctrl+X to save

This step is the one most guides skip, and it’s the reason SSH says “Connection refused” even when everything else looks right.

Unmount safely before pulling the card

sudo umount /media/$USER/bootfs
sudo umount /media/$USER/rootfs

First boot — use ethernet

Don’t try to get WiFi working on the first boot. Use an ethernet cable from your router directly to the Pi. This sidesteps a whole class of problems and lets you get a shell quickly, after which WiFi config from inside the Pi is straightforward.

  1. Insert the SD card into the Pi
  2. Plug in the ethernet cable
  3. Plug in power
  4. Wait 2 full minutes — first boot resizes the filesystem and takes longer than subsequent boots

Once it’s had time to boot, check that it’s on the network:

ping raspberrypi.local

Then SSH in:

ssh yourusername@raspberrypi.local

Configure WiFi from inside the Pi

Once you have a shell, use nmcli to connect to your WiFi network. The key here is using nmcli con add rather than nmcli device wifi connect — the latter often fails with a cryptic key-mgmt missing error:

# Scan for networks
sudo nmcli device wifi list

# Connect to your network
sudo nmcli con add type wifi ssid "YourNetworkName" \
  con-name "home-wifi" \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "YourPassword" \
  ipv4.method auto

sudo nmcli con up "home-wifi"

Verify that WiFi got an IP address:

ip addr show wlan0

You should see an IP assigned to wlan0. Once confirmed, unplug the ethernet cable and SSH in over WiFi from your laptop:

ssh yourusername@raspberrypi.local

If it connects, you’re done.

Sanity check

uname -a          # confirms OS version
python3 --version # confirms Python available
ping google.com -c 3  # confirms internet works

Troubleshooting

If something doesn’t work, this table covers the most common issues:

Problem Fix
ssh: Could not resolve hostname Use IP directly: ssh user@192.168.1.x
Connection refused SSH not enabled — create ssh file and userconf.txt
Pi not on network Use ethernet first, configure WiFi from inside
rpi-imager write fails Unmount card first: sudo umount /media/$USER/bootfs
nmcli WiFi error key-mgmt missing Use full nmcli con add command above, not nmcli device wifi connect
Can't find Pi IP Run sudo nmap -sn 192.168.1.0/24 and look for new device

Quick reference

Written April 2026 based on hands-on setup experience with Raspberry Pi OS Bookworm on Ubuntu 24.