Skip to content

Raspberry Pi Headless Setup 2026 with Imager and SSH

Already stuck at first boot? Use the interactive headless setup troubleshooter to separate boot, DHCP, mDNS, SSH timeout, connection-refused, key, host-identity, and USB Gadget failures.

Set up a headless Raspberry Pi by configuring the user, hostname, network, and SSH key in Raspberry Pi Imager before writing the storage device. This is more reliable than depending on retired default credentials or editing boot files with instructions written for older Raspberry Pi OS releases.

Choose the first connection

Connection Use it when What to configure in Imager
Ethernet + SSH Router and cable are available Hostname, user, SSH key
Wi-Fi + SSH The Pi must join a known wireless LAN Hostname, user, Wi-Fi country/SSID, SSH key
USB Gadget + SSH No LAN is usable Hostname, user, SSH key, USB Gadget Mode

Ethernet is the simplest diagnostic baseline. USB Gadget Mode is useful in hotels, classrooms, and recovery situations. See the headless and networking hub for remote-access choices after first boot.

What you need

  • Supported Raspberry Pi
  • Correct stable power supply
  • microSD, USB SSD, or NVMe storage supported by the board and bootloader
  • Another computer running current Raspberry Pi Imager
  • Ethernet, Wi-Fi credentials, or a USB data cable
  • An SSH key pair on the computer you will connect from

Do not assume the old pi user or raspberry password exists. Current images require you to create an account.

Step 1: create an SSH key

On the client computer:

1
ssh-keygen -t ed25519 -a 64

Accept the default location unless you manage keys another way, and protect the private key with a passphrase. Display the public key:

1
cat "$HOME/.ssh/id_ed25519.pub"

Only the .pub content belongs in Imager. Never copy the private key onto the Raspberry Pi image.

Step 2: configure Raspberry Pi Imager

Download Imager from the official Raspberry Pi software page.

  1. Select the exact Raspberry Pi device.
  2. Choose the current 64-bit Raspberry Pi OS, or Lite for a server without a desktop.
  3. Select the target storage device carefully.
  4. Open OS customisation.
  5. Set a unique hostname, for example pi-lab-01.
  6. Create a unique username and strong password.
  7. Set timezone, keyboard, and Wi-Fi country.
  8. Configure Wi-Fi only if you intend to use it.
  9. Enable SSH and choose public-key authentication.
  10. Add the public key from the client computer.
  11. Enable USB Gadget Mode only when that is your first connection.
  12. Write and verify the image.

Selecting the wrong target erases the wrong storage device. Confirm the device model and capacity immediately before writing.

Step 3: first boot

  1. Insert or connect the newly written storage.
  2. Attach Ethernet, Wi-Fi antenna arrangement, or the correct USB Gadget port as planned.
  3. Apply stable power.
  4. Wait for initial provisioning to finish.

First boot can take longer than later boots. Avoid removing power while filesystem expansion, package setup, or provisioning is in progress.

Step 4: connect over SSH

Try the configured hostname:

1
ssh your-user@pi-lab-01.local

If .local resolution is not available, use the address from your router's DHCP leases or authorised network inventory.

For USB Gadget Mode, try the configured hostname and then the documented fallback address:

1
ssh your-user@10.12.194.1

Follow USB Gadget Mode: SSH over USB for host drivers and internet sharing.

On the first connection, compare the SSH host-key fingerprint with a trusted local value if the device is security-sensitive. Do not train users to accept every unknown key automatically.

Step 5: verify the installation

1
2
3
4
5
6
7
8
9
hostnamectl
cat /etc/os-release
uname -m
ip -brief address
ip route
nmcli connection show --active
timedatectl status
vcgencmd get_throttled
systemctl --failed

Update through the normal package system:

1
2
3
sudo apt update
sudo apt full-upgrade
sudo reboot

Raspberry Pi OS 6.2 and later prompts for the administrator password on new installations when sudo is used. This is expected security behaviour, not an SSH failure.

Step 6: verify SSH security

Check the effective configuration:

1
2
sudo sshd -t
sudo sshd -T | grep -E 'pubkeyauthentication|passwordauthentication|permitrootlogin'

Before disabling password authentication, open a second SSH session and prove that the key works. Then create a small override instead of rewriting the vendor configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
sudo install -d -m 0755 /etc/ssh/sshd_config.d
sudo tee /etc/ssh/sshd_config.d/10-headless-security.conf >/dev/null <<'EOF'
PermitRootLogin no
PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no
EOF

sudo sshd -t
sudo systemctl reload ssh

Keep the first session open until a new key-authenticated connection succeeds. If you lose access, use the recovery method planned before the change.

NetworkManager checks

Raspberry Pi OS Trixie uses NetworkManager for normal Wi-Fi and Ethernet profile management.

1
2
3
nmcli device status
nmcli connection show
nmcli general status

Connect to Wi-Fi interactively when provisioning credentials after first boot:

1
sudo nmtui

Or use nmcli while avoiding password exposure in shared terminal history:

1
2
nmcli device wifi list
sudo nmcli --ask device wifi connect "YOUR-SSID"

For static addresses and DNS, follow NetworkManager and nmcli on Raspberry Pi.

Use a DHCP reservation before a static profile

When you control the router, a DHCP reservation usually gives the Pi a stable address while keeping address management central. A device-side static profile is appropriate for deployments where the address plan is controlled and documented.

Do not assign a static address that can also be handed to another client by DHCP.

Optional remote access

After local SSH works, choose a remote path:

  • Raspberry Pi Connect for browser-mediated remote access and supported remote functions.
  • Tailscale for private SSH and service access across networks.
  • VNC optimisation only when a graphical desktop is required and protected by a private network.

Avoid direct router port forwarding for SSH or VNC unless you operate the complete security boundary and monitoring.

Back up before installing the workload

Record a clean, working baseline:

1
2
3
4
5
mkdir -p "$HOME/setup-baseline"
cp /etc/os-release "$HOME/setup-baseline/"
nmcli connection show --active > "$HOME/setup-baseline/connections.txt"
systemctl --failed > "$HOME/setup-baseline/failed-units.txt"
dpkg-query -W > "$HOME/setup-baseline/packages.txt"

Do not copy NetworkManager files containing Wi-Fi secrets into an unencrypted repository.

Create a tested storage backup or maintain a reproducible provisioning process before deploying the application.

Troubleshooting

The hostname does not resolve

.local requires mDNS support. Check the DHCP lease on your router or use the known USB Gadget fallback address. Do not run network scans without authorisation.

SSH connection is refused

The address responds but the SSH server is not listening. With local or recovery access:

1
2
3
sudo systemctl enable --now ssh
sudo ss -lntp | grep ':22'
journalctl -b -u ssh --no-pager

SSH times out

Check link, address, route, and firewall in that order:

1
2
3
4
ip -brief link
ip -brief address
ip route
sudo nft list ruleset

Permission denied (publickey)

Use the correct username and private key:

1
ssh -vvv -i "$HOME/.ssh/id_ed25519" your-user@pi-lab-01.local

On the Pi, .ssh should normally be mode 700 and authorized_keys mode 600, owned by the target user.

Wi-Fi does not connect

1
2
3
4
rfkill list
nmcli radio wifi
nmcli device wifi list
journalctl -b -u NetworkManager --no-pager

Confirm country, SSID spelling, supported band, authentication mode, and signal. Some Raspberry Pi models do not support 5 GHz.

USB Gadget does not appear

Confirm Trixie, correct device-mode port, data cable, host driver, and adequate power. See the dedicated USB Gadget troubleshooting guide.

FAQ

Can I set up a Raspberry Pi without a monitor?

Yes. Configure the account, network, and SSH key in Imager. Connect by Ethernet, Wi-Fi, or supported USB Gadget Mode.

What is the default Raspberry Pi username and password?

Current Raspberry Pi OS installations do not depend on the retired pi/raspberry default. Create a unique account in Imager or the first-boot wizard.

Should I create an empty ssh file on bootfs?

Use Imager's SSH setting for current installations because it configures the user and authentication method together. The empty-file method belongs to older/manual workflows and does not solve user provisioning by itself.

Do I need Wi-Fi for headless setup?

No. Ethernet or USB Gadget Mode can provide the first SSH connection.

What should I do before changing the network remotely?

Keep the current session open, prepare an automatic rollback or alternate connection, change one profile at a time, and verify from a second terminal.