To SSHSSH A secure way to type commands on a server from your own computer, as if you were sitting at it. More about SSH → into a Raspberry Pi, turn SSH on (it is off by default), find the Pi’s name or address on your network, then run ssh username@raspberrypi.local from another computer. This guide is for anyone setting up a Pi as a small home server, with or without a screen and keyboard attached.
Enable SSH in Raspberry Pi Imager’s customisation settings before you write the card, or later with sudo raspi-config (Interface Options, then SSH). From a computer on the same network, run **ssh yourname@raspberrypi.local**, using the username you created and the hostname you chose. If the name does not resolve, use the Pi’s local IP addressIP address The number address of a device on the internet, like 203.0.113.10. Computers use it to find each other, the way post uses street addresses. More about IP address → instead, which hostname -I shows on the Pi.
What you need before you start
- A Raspberry Pi running Raspberry Pi OS (or another Linux system such as Ubuntu for Pi).
- The Pi and your computer on the same network: the same home Wi-Fi or router.
- The username and password you set when you installed the system. Current Raspberry Pi OS releases have no default
piuser with the passwordraspberry; you create your own account during setup. - An SSH client. macOS, Linux and Windows 10 and 11 all include the
sshcommand, so you can use Terminal or PowerShell. If you have never used it, the SSH basics guide listed under Related walks you through it.
SSH gives you an encrypted command line on the Pi, so once it works you can manage the Pi from your desk and unplug its screen for good.
Step 1: turn on SSH
SSH is switched off on a fresh Raspberry Pi OS install, for safety. Pick the method that matches your situation.
Option A: before first boot, with Raspberry Pi Imager
This is the easiest route and the only one you need for a “headless” Pi (one with no screen or keyboard).
- Open Raspberry Pi Imager on your computer and choose your Pi model, the operating system and your microSD card.
- When Imager offers to customise the system, accept.
- Set a hostname (for example
pi-server), a username and a password. - If the Pi will use Wi-Fi, enter your network name and password.
- In the remote access settings, turn on SSH. You can allow password login, or paste in a public key if you already have one (see Step 4).
- Write the card, put it in the Pi and power it on. Give it a minute or two on first boot.
Older guides tell you to create an empty file called ssh on the card’s boot partition. Recent Raspberry Pi OS releases handle first-boot setup differently, so use Imager’s settings instead: they also create your user account, which SSH needs.
Option B: on a Pi that is already running
If you have a screen and keyboard attached, or the desktop open, run this in a terminal on the Pi:
sudo raspi-config
Choose Interface Options, then SSH, then Yes. Select Finish to leave.
You can also do it with one command, which starts the SSH service now and every time the Pi boots:
sudo systemctl enable --now ssh
Check it is running:
systemctl status ssh
Success looks like active (running) in green.
Step 2: find the Pi on your network
You can reach the Pi by its name or by its IP address.
By name
Raspberry Pi OS announces its hostname on the local network using mDNS (multicast DNSDNS The internet’s phone book. It turns a name people can remember, like example.com, into the number address computers use to find the server. More about DNS →), so most computers can reach it as hostname.local. If you kept the default name, that is raspberrypi.local; if you set pi-server in Imager, it is pi-server.local. Test it from your computer:
ping raspberrypi.local
Replies mean the name works. Press Ctrl+C to stop.
By IP address
If the name does not resolve, use the Pi’s local IP address. On the Pi itself, run:
hostname -I
The first address shown is usually the one you want. On a home network it typically starts with 192.168. or 10.. In this guide we use 192.0.2.25 as the example. The guide to checking your IP address in Linux (see Related) covers the other ways to find it.
No screen on the Pi? Log in to your router’s admin page and look at the list of connected devices for one named after your Pi’s hostname.
Your router can hand the Pi a different address after a restart. If you plan to connect often by IP, reserve an address for the Pi in your router’s DHCP settings (often called “DHCP reservation” or “static lease”).
Step 3: connect
From your computer, open Terminal (macOS or Linux) or PowerShell (Windows) and run, replacing exampleco with your username:
ssh exampleco@raspberrypi.local
Or by address:
ssh exampleco@192.0.2.25
The first time, SSH shows the Pi’s fingerprint and asks Are you sure you want to continue connecting (yes/no/[fingerprint])?. Type yes and press Enter. Your computer remembers the Pi from now on.
Then type your password. Nothing appears on screen as you type; that is normal. Press Enter.
Success looks like a prompt such as:
exampleco@raspberrypi:~ $
Every command you type now runs on the Pi. Type exit to disconnect.
Step 4: switch to SSH keys
Passwords work, but an SSH key is safer and saves typing. Create a key on your computer and copy it to the Pi:
ssh-keygen -t ed25519 -C "my-laptop"
ssh-copy-id exampleco@raspberrypi.local
On Windows, where ssh-copy-id is not included, use the PowerShell method in our SSH keys guide (see Related), which also shows how to turn off password login once the key works. Test the key in a second window before you switch passwords off, so you cannot lock yourself out.
To save typing the full command each time, add a shortcut to ~/.ssh/config on your computer:
Host pi
HostName raspberrypi.local
User exampleco
Now ssh pi is enough.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
ssh: Could not resolve hostname raspberrypi.local | mDNS not working on your computer or network, or a different hostname was set | Use the IP address from hostname -I or your router’s device list, and check the hostname you chose in Imager |
Connection refused | The Pi is reachable but SSH is off | Enable SSH with sudo raspi-config or sudo systemctl enable --now ssh |
Connection timed out or No route to host | Wrong IP, Pi not on the network yet, or your computer is on a guest or different network | Wait for boot to finish, confirm the address, and join the same network as the Pi |
Permission denied, please try again | Wrong username or password | Use the account you created in Imager, not pi, unless you named it that |
WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! | You reinstalled the Pi, so it has a new host key | If you know you reflashed it, remove the old entry with ssh-keygen -R raspberrypi.local (or the IP) and connect again |
| Wi-Fi Pi never appears on the network | Wi-Fi name or password mistyped in Imager | Rewrite the card with the correct details, or connect a network cable for the first boot |
Reaching your Pi from outside your home
Everything above works on your local network. Connecting from the internet is a different matter: forwarding portPort A numbered door on a server. Each service listens behind its own door: web pages on 443, email on others, remote login on 22. More about Port → 22 on your router straight to the Pi exposes it to constant automated login attempts. If you need remote access, a VPN into your home network (such as WireGuard) is the safer route. Whatever you choose, use SSH keys, turn off password login and consider a firewall on the Pi.
Official documentation
Related
- How to connect to a server with SSH: the SSH basics, including copying files and staying connected.
- How to set up SSH keys: replace your Pi’s password login with a key pair.
- How to check your IP address in Linux: every way to find the address your Pi is using.
- Git Bash for Windows: a handy terminal for SSH from a Windows PC.
Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.



