Raspberry Pi Headless Setup 2026 with Imager and SSH¶
A headless Raspberry Pi runs without a monitor, keyboard or mouse. Set its username, network and SSH public key in Raspberry Pi Imager before writing the card. After powering it on, connect from another computer using the hostname you chose. If the name does not resolve, use the Pi's IP address from your router.
Set up Imager · Find the Pi and connect · Read your SSH error
For a monitor-based first boot, see Initial Setup. If you use a Pi 5, check its power and boot behaviour.
What you need¶
- A supported Raspberry Pi, appropriate power supply, microSD card and reader. Start with microSD if USB/NVMe boot is not already verified.
- A client computer with Raspberry Pi Imager and an OpenSSH client. Commands labelled client run on that computer, not the Pi.
- A reachable home/lab LAN: Ethernet when your board has it, or compatible Wi-Fi with known credentials. Guest/client isolation can prevent SSH even when both devices have internet access.
- A recovery plan if first boot fails, such as a local display/keyboard or access to the card and a second computer.
Choose Raspberry Pi OS Lite for a terminal-only project, or Desktop if you will need a graphical session. Use Imager's exact-device filter for image compatibility; not every model supports the same 64-bit image. Pico does not use this Linux installation workflow.
Outcome: reach the intended Pi with the intended account, open a second independent SSH login and verify service startup before planning a reboot.
Choose the first connection¶
Use Ethernet when available to avoid Wi-Fi provisioning variables. Otherwise configure Wi-Fi in Imager. Neither path requires a static address or router port forwarding.
No usable LAN? Follow the separate USB Gadget SSH procedure for its supported model, OS, data port, host driver and power requirements. Do not apply a USB fallback IP to an ordinary Wi-Fi/Ethernet installation.
Step 1: create an SSH key¶
On the client, use an existing suitable key if you already manage one. Otherwise, Linux/macOS terminal or Windows PowerShell with OpenSSH can generate a key:
This creates files on the client. Read the proposed destination; if a key already exists there, do not overwrite it. Cancel and use the existing public key or choose a distinct filename. Protect the private key with a passphrase and retain it on the client.
In Imager, browse to the matching public key file ending in .pub. For example, the default is normally id_ed25519.pub in the client's .ssh directory. Copy only that public key, never its private counterpart. This procedure uses key authentication; the official guide also explains Imager's password-authentication option.
Step 2: configure Raspberry Pi Imager¶
On the client, install official Raspberry Pi Imager. Select your exact device, a supported Raspberry Pi OS image and the intended card. Current Imager uses guided customisation screens; older gear-icon screenshots may differ.
Before writing, set:
- A unique hostname, such as
pi-lab-01. - Your own username and strong account password. There is no universal
pi/raspberryaccount. Keep this password even with SSH keys: administrator authentication is separate. - Your location, time zone and keyboard layout; configure the appropriate Wi-Fi regulatory country where offered.
- Wi-Fi SSID and password if using wireless networking. Verify spelling and the board's supported band. Ethernet normally uses DHCP without Wi-Fi credentials.
- Remote Access → Enable SSH → public-key authentication, supplying the public key from Step 1.
Writing erases the selected storage
Back up required files. Check the storage name and capacity again before Write, retain Imager's system-drive protection and allow verification to finish. If the card cannot be identified confidently, stop rather than guess. Do not overwrite a working Pi installation merely to enable SSH.
For the full Device → OS → Storage walkthrough, see the installation screens in Initial Setup. Do not add legacy wpa_supplicant.conf files or enable several remote-access services to complete this LAN test.
Step 3: first boot¶
Safely remove the verified card from the client, insert it into the unpowered Pi, attach Ethernet if selected, then apply the correct power supply. Allow provisioning to complete; do not repeatedly interrupt power. On models without Ethernet, use the Wi-Fi settings prepared in Imager.
Keep the client on a network that can reach the Pi. Record the configured username and hostname, not a guessed default. Pi 5 power-button/status-light and peripheral checks are in the model-specific checklist.
Step 4: connect over SSH¶
Try the hostname from Imager¶
Open a terminal on your client computer (PowerShell on Windows or Terminal on macOS and Linux). In this example Imager used the hostname pi-lab-01. Replace it and your-user with the values you entered. Leave the .local suffix in place.
Raspberry Pi OS announces the name on the local network using multicast DNS (mDNS). Your client and network must support that lookup. If SSH reports Could not resolve hostname, try the router-assigned IP below. If it asks about an unfamiliar host key, verify the Pi's identity before accepting.
Find the Pi's IP address in the router¶
Open the router's app or admin page and look for Connected devices, Clients or DHCP leases. On a managed network, ask the administrator.
- Find an active entry with the hostname you set in Imager, such as
pi-lab-01. Check that its connection type matches your Ethernet or Wi-Fi setup if the router shows it. An old lease can remain listed after a device disconnects. - Copy the entry's IPv4 address. If the router hides the name or shows several possible entries, use a monitor to run
ip -brief addresson the Pi, or ask the network administrator to confirm its address. - From your client, replace
192.168.1.42with the address you confirmed:
If SSH works by IP, the Pi is reachable and you can use that address even if .local fails. If the Pi has no active entry, first check boot, Ethernet or Imager's Wi-Fi settings. Changing the SSH key will not help the Pi join the network.
If you saved the key under a custom filename in Step 1, add -i "path/to/private-key" before the destination in either command. Use the matching private key on the client.
Verify the host key on first login¶
A host key identifies the SSH server. Check the fingerprint in the first-login prompt through a trusted independent route before accepting it. For an ED25519 prompt, run this from a trusted local console on the Pi:
Compare the fingerprint and key type with the client's prompt. If the fingerprint differs, cancel the connection and check the intended Pi's address. You may see a new prompt when you switch from hostname to IP. If the client warns that a known key changed, verify the device and its reimaging history before updating the entry.
Step 5: verify the installation¶
After authentication, run these read-only checks on the Pi:
Confirm the intended hostname/OS, the active LAN interface and its route. In a normal service-based Raspberry Pi OS setup, active means SSH is running now; enabled means it is configured to start on boot. A custom socket-activated setup needs its own interpretation. If startup is wrong, use the initial setup SSH-startup check with local/recovery access rather than blindly replacing configuration.
Open a second client terminal and repeat the login before closing the first. If Imager selected key-only authentication, you should authenticate with the intended key; a key passphrase prompt unlocks the client key and is not the Pi account-password prompt.
Step 6: verify SSH security¶
For this first-login gate, keep host identity checks enabled, retain the client private key, and do not forward SSH publicly through the router. Do not change server authentication, firewall policy or network profiles merely because login succeeded.
Once both logins work, continue with updates and reconnection after reboot. These are system-changing steps: review APT's proposed actions, check recovery and service startup, and reboot only after a successful update. The Trixie sudo guide explains administrator-password prompts separately from SSH login.
Further access-policy changes belong to security hardening, not an additional mandatory first-boot script.
Troubleshooting¶
| What you see | What to check next |
|---|---|
Could not resolve hostname |
Check the spelling or use the router-assigned IP. |
Connection timed out |
Confirm the IP is current and the client can reach the Pi's network. Check for guest Wi-Fi isolation or filtering. |
Connection refused |
Confirm you reached the intended address, then check that SSH is enabled and listening on the Pi. |
Permission denied (publickey) |
The server answered. Confirm your Imager username and the key your client offered. |
REMOTE HOST IDENTIFICATION HAS CHANGED |
Check the server's identity before changing any saved key. |
For recovery steps, see the headless troubleshooter. For a Pi connected directly over USB, follow the USB Gadget prerequisites.
Optional remote access¶
This LAN login does not automatically work from outside home. For browser access or a desktop, use the remote-access chooser. For different connectivity requirements, use the connection route map. Lite still has no graphical desktop to share.
Check your understanding¶
Which key stays on the client, and which goes into Imager? Why can .local fail while the numeric address works? What proves that SSH runs now, and what still needs checking before reboot?
Next, use safe terminal practice after completing the update/reconnection check. Network profile changes belong to NetworkManager and nmcli, not another OS installation.