:INFO Most headless guides on the internet are broken for the Pi you just bought The two-file trick everyone remembers, an empty "ssh" file plus a "wpa_supplicant.conf" in the boot partition, was deprecated in Bullseye and completely removed in Bookworm. Placing wpa_supplicant.conf has zero effect: Bookworm switched to NetworkManager, which never reads that file. The correct path is Raspberry Pi Imager v2.x, which embeds your Wi-Fi credentials and SSH settings in a firstrun.sh script on the card before you ever insert it into the Pi. This tutorial covers exactly that path, then walks you through every SSH error you are likely to hit on first connect. You need a laptop or desktop with an SD card slot or adapter, a microSD card of at least 8 GB, and about 20 minutes. :IMAGE :STATS [icon:CLOCK] Time needed | About 20 minutes [icon:TARGET] Cost | Free [icon:FIRE] Difficulty | Beginner, no Linux experience required [icon:CHECK] OS version | Raspberry Pi OS Bookworm (use this, not Trixie) [icon:BOLT] Imager version | 2.0.6 or later :INFO Step 1. Download and open Raspberry Pi Imager Go to raspberrypi.com/software and download the Imager for your platform (Windows, macOS, or Ubuntu). Install and open it. The UI has three large buttons at the top: Choose Device, Choose OS, and Choose Storage. Work through them in order. :LINK https://www.raspberrypi.com/software/ Raspberry Pi Imager: official download page :INFO Step 2. Select your device, OS, and storage Click Choose Device and pick your Pi model. This filters the OS list to compatible images. Click Choose OS, then select "Raspberry Pi OS Lite (64-bit)" for a headless server (no desktop) or "Raspberry Pi OS (64-bit)" for a desktop you will VNC into later. If you own a Pi Zero W or Zero 2W, the Lite image is the right choice. Click Choose Storage and select your microSD card. Triple-check the drive letter before proceeding. :NOTE Stay on Bookworm. Trixie (the Debian 13-based beta) has two confirmed issues: the Imager customisation script does not run on some images, leaving SSH and Wi-Fi unconfigured, and NetworkManager on Trixie has a regression where Wi-Fi connects once and then stops reconnecting. Use the standard Bookworm image until Trixie is declared stable. :INFO Step 3. Open OS Customisation and fill in every field Click Next. Imager asks "Would you like to apply OS customisation settings?" Click "Edit Settings". This opens a panel with two tabs. On the General tab, fill in all of these: • Hostname: change from "raspberrypi" to something unique, for example "pi-home". Your Pi becomes reachable at pi-home.local. • Username: set your own username. The old default "pi" with password "raspberry" does not exist in Bookworm and never will. • Password: set a strong password. • Configure wireless LAN: tick the box, enter your SSID and password. • Wireless LAN country: set your two-letter code (US, GB, FR, etc.). Wi-Fi will not start without this. • Set locale settings: set your timezone and keyboard layout. On the Services tab, enable SSH. Choose "Use password authentication" for now. You can switch to key-only later once you have confirmed login. Click Save. :NOTE Pi Zero W and Zero 2W support 2.4 GHz networks only. If your router broadcasts two networks (e.g. "HomeNet" at 2.4 GHz and "HomeNet-5G" at 5 GHz), enter the 2.4 GHz SSID. Entering the 5 GHz one silently fails to connect. :INFO Step 4. Write the card and boot the Pi Click Yes to apply customisation, then confirm the write. Imager downloads the OS, writes it, and verifies the card. This takes 3 to 10 minutes depending on your connection and card speed. When it finishes, eject the card safely, insert it into the Pi, and connect power. First boot is slow: the Pi expands the filesystem, applies your settings, and may reboot once. Wait at least 90 seconds before you try to connect. :INFO Step 5. Connect via SSH Open a terminal (Terminal on Mac or Linux, PowerShell on Windows 10 and 11). Try the mDNS hostname first, substituting your chosen hostname: :CODE [language:bash] ssh yourusername@pi-home.local If that works, you are done. If it does not, try finding the Pi's IP \ address using one of the methods in the next section, then connect by \ IP instead: :CODE [language:bash] ssh yourusername@192.168.1.47 :INFO Finding the Pi's IP address when mDNS fails Three methods, in order of ease: • Router admin panel: go to 192.168.1.1 or 192.168.0.1, log in, and look at the DHCP lease or connected devices table. The Pi appears with its hostname and an IP like 192.168.1.47. • Ping: run "ping pi-home.local" in your terminal. If it resolves, the reply shows the IP address. • nmap: scan your subnet. The Pi shows up as "Raspberry Pi Foundation". :CODE [language:bash] nmap -sn 192.168.1.0/24 Replace "192.168.1" with your own subnet prefix if different. Raspberry \ Pi Foundation MAC prefixes: b8:27:eb (older models), dc:a6:32 (Pi 4), \ e4:5f:01 (Pi 5 and Zero 2W). :INFO Fixing every common SSH error If SSH does not work on first try, the error message tells you exactly what is wrong. Here are the four you are most likely to see. :TABLE [title:SSH error quick-fix] Error | What it means | Fix Connection refused | SSH daemon is not running | Re-flash the card; confirm SSH is enabled in the Services tab before writing No route to host | Pi is not on the network | Check Wi-Fi credentials, country code, and that you used a 2.4 GHz SSID for Zero W models Permission denied | Wrong username or password | Use the username you set in Imager, not "pi"; type the password carefully (nothing echoes) Host key verification failed | SD card was re-flashed | Run ssh-keygen -R pi-home.local to clear the old fingerprint :INFO Clearing a stale host key If you re-flash the SD card and try to reconnect, SSH will refuse with a large warning about a changed host key. This is correct behaviour: SSH detected that the server fingerprint changed. Fix it with one command on your local machine: :CODE [language:bash] ssh-keygen -R pi-home.local Or by IP address if you used one: :CODE [language:bash] ssh-keygen -R 192.168.1.47 This removes only the old entry from your known_hosts file and creates \ a backup. SSH again and accept the new fingerprint when prompted. :INFO Step 6. First things to do after login Once you are in, update the system before anything else. This takes 2 to 5 minutes on a fresh Pi. :CODE [language:bash] sudo apt update && sudo apt upgrade -y Change your password if you want a stronger one: :CODE [language:bash] passwd Check the Pi's hostname and that you are running Bookworm: :CODE [language:bash] hostnamectl cat /etc/os-release | grep PRETTY_NAME If you plan to use this Pi long-term, now is the time to set up SSH \ key authentication and disable password login entirely. The official \ Raspberry Pi documentation has the exact steps. :LINK https://www.raspberrypi.com/documentation/computers/remote-access.html Raspberry Pi official docs: remote access and SSH configuration :NOTE The manual workaround without Imager exists but is fragile. You need a "userconf.txt" file in the boot partition with a hashed password, plus a hand-written .nmconnection file on the rootfs partition for Wi-Fi. The Imager path is shorter and more reliable. Only go manual if the Imager is unavailable.