How to Enable SSH in Raspberry Pi 5: Headless Setup & Remote GPIO Control

The fastest way to enable SSH in Raspberry Pi for a headless setup is to place an empty file named exactly ssh (with no file extension) in the root directory of the FAT32 boot partition before your first boot. When Raspberry Pi OS boots, it detects this file, enables the SSH daemon, and automatically deletes the file.

While the concept is simple, execution on the workbench often fails due to hidden file extensions, partition confusion, or mDNS resolution timeouts. This guide walks through the exact hardware requirements for the Raspberry Pi 5, the precise file creation process, and a complete Python script to verify your remote connection by toggling a GPIO pin.

The Headless SSH Boot: Parts and Prep

This guide targets the Raspberry Pi 5 (8GB RAM variant) running Raspberry Pi OS (Bookworm or newer, 64-bit). The Pi 5 has stricter power delivery requirements than the Pi 4; attempting to run it on a standard 5V/3A phone charger will result in peripheral brownouts and USB port disabling.

Hardware & Software Bill of Materials

Step-by-Step: Creating the Boot Partition ssh File

The most common reason a headless boot fails is writing the ssh file to the wrong partition. The microSD card contains two partitions after flashing: a small FAT32 bootfs partition and a large ext4 rootfs partition. Windows and macOS will only mount the FAT32 boot partition automatically. This is exactly where the file must go.

1. Flash the OS: Use Raspberry Pi Imager to write Raspberry Pi OS (64-bit) to your microSD card. Eject and reinsert the card to force your OS to remount the boot partition.
2. Open the Boot Drive: Open the drive labeled bootfs (Windows) or boot (macOS) in your file explorer.
3. Create the File: Create a new, completely empty file. Name it exactly ssh.
4. Verify Extensions (Windows Critical Step): Windows hides known file extensions by default. If you name the file ssh in a text editor, Windows will silently save it as ssh.txt. The Pi will ignore this. In Windows Explorer, go to View > Show > File name extensions. Ensure the file is named ssh with absolutely no trailing .txt.
5. Configure WiFi (Optional but Recommended): If you aren't using Ethernet, create a file named wpa_supplicant.conf in the same boot directory with your network credentials, or use the Imager's pre-configuration menu (detailed in the FAQ).
6. Boot the Pi: Insert the card into the Pi 5, connect the 27W power supply, and wait 60-90 seconds for the first-boot resize and daemon initialization.

Remote GPIO Control: Verifying SSH with a Python Script

Once you successfully SSH into the Pi (ssh your_username@raspberrypi.local), the best way to verify system health and GPIO permissions is to run a physical hardware test. We will blink an LED using the gpiozero library, which is pre-installed on Raspberry Pi OS.

Pin Mapping Table

Complete Python Verification Script

This script targets the Pi 5 GPIO architecture. It includes explicit error handling to ensure the GPIO hardware is safely released if the SSH session drops or the user interrupts the process.

#!/usr/bin/env python3
"""
Remote GPIO Verification Script
Target Board: Raspberry Pi 5 (8GB)
OS: Raspberry Pi OS (Bookworm 64-bit)
Dependencies: gpiozero (pre-installed)
"""

from gpiozero import LED
from time import sleep
import sys

# Pin definition: Physical Pin 11 maps to BCM GPIO 17
LED_PIN = 17
led = LED(LED_PIN)

def main():
    print(f"[INFO] Blinking LED on GPIO {LED_PIN} (Physical Pin 11).")
    print("[INFO] Press CTRL+C to stop and safely release GPIO resources.")
    
    try:
        while True:
            led.on()
            sleep(0.5)
            led.off()
            sleep(0.5)
    except KeyboardInterrupt:
        print("\n[WARN] Keyboard interrupt received. Halting script...")
    except Exception as e:
        print(f"[ERROR] Unexpected GPIO or system failure: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        # gpiozero handles cleanup automatically on exit, but explicit close is best practice
        led.close()
        print("[INFO] GPIO resources released. LED should now be off.")

if __name__ == "__main__":
    main()

Save this file over your SSH session using nano blink_test.py, then execute it with python3 blink_test.py. If the LED blinks, your headless setup, network routing, and GPIO permissions are fully operational.

Troubleshooting: Connection Refused and Other SSH Errors

When a headless boot fails, the terminal usually throws one of two errors. Understanding the distinction saves hours of reflashing SD cards.

Error 1: ssh: connect to host raspberrypi.local port 22: Connection refused

Meaning: Your computer found the Pi on the network (mDNS resolved), but the Pi actively rejected the connection on port 22.

Ranked Causes:

1. The ssh file was missing, had a .txt extension, or was placed in the rootfs partition instead of bootfs.
2. The Pi is still in the middle of its first-boot partition resize (wait another 2 minutes).
3. SSH daemon crashed due to a corrupted OS flash.

Error 2: ssh: Could not resolve hostname raspberrypi.local: nodename nor servname provided

Meaning: The SSH client cannot translate the .local mDNS address to an IP address.

Ranked Causes:

1. mDNS (Bonjour/Avahi) is blocked on your router or VLAN.
2. The Pi failed to connect to WiFi (check wpa_supplicant.conf syntax).
3. Your Windows machine lacks the Bonjour Print Services or Apple device network support.

Frequently Asked Questions

How do I enable SSH in Raspberry Pi without a monitor on the first boot?

As detailed in the steps above, the standard method is the empty ssh file in the boot partition. However, if you have physical access to the Pi post-boot but no monitor, you can pull the SD card, insert it into a PC, and use a tool like ext4cfg (Linux) to mount the rootfs partition and run sudo systemctl enable ssh via chroot. For 99% of users, the boot partition file method is vastly superior and less prone to filesystem corruption.

How do I enable SSH in Raspberry Pi using the Raspberry Pi Imager?

The Raspberry Pi Imager provides a GUI method that eliminates the need for manual file creation. When selecting your OS in the Imager, click the "Edit Settings" button (or press Ctrl+Shift+X on older versions). Under the Services tab, check "Enable SSH" and select "Use password authentication" (or paste your public ED25519 key for better security). The Imager will inject the correct configuration files into the OS image before flashing.

Can I enable SSH in Raspberry Pi over WiFi without an Ethernet cable?

Yes, but you must also provide WiFi credentials during the headless setup. If using the manual file method, create a wpa_supplicant.conf file in the boot partition alongside the ssh file. If using the Raspberry Pi Imager GUI, simply enter your SSID and password in the "Wireless LAN" settings menu. Note that the Pi 5 supports 802.11ac (WiFi 5) dual-band; ensure your wpa_supplicant.conf specifies the correct country code (e.g., country=US) or the 5GHz radio will remain disabled by regulatory domains.

How do I extend this build for secure remote access?

Once you have basic SSH working, you should immediately disable password authentication to prevent brute-force botnet attacks. Generate an ED25519 keypair on your host machine (ssh-keygen -t ed25519), copy it to the Pi using ssh-copy-id your_username@raspberrypi.local, and then edit /etc/ssh/sshd_config on the Pi to set PasswordAuthentication no. Restart the daemon with sudo systemctl restart ssh. For access outside your local network, avoid port forwarding port 22; instead, use a secure tunnel service like Cloudflare Tunnels or Tailscale.