Raspberry Pi online course

Enable and Use SSH on Raspberry Pi OS

Learn how to enable SSH on Raspberry Pi OS, find your Pi on the network, connect from Windows, macOS, or Linux, transfer files, and troubleshoot common SSH problems.

What SSH does

SSH, or Secure Shell, is an encrypted protocol for remote command-line access. It lets you administer a Raspberry Pi over a local network or another reachable network without connecting a monitor and keyboard to the Pi.

The SSH server runs on the Raspberry Pi. It is commonly provided by OpenSSH and includes the sshd server process. The SSH client runs on the computer you use to connect; examples include the ssh command, PuTTY, and graphical SFTP applications.

SSH encrypts login credentials and session traffic. Encryption does not make every setup safe automatically: use strong credentials, verify the server identity, keep software updated, and restrict which networks can reach the service.

For background on terminal use, see Terminal in Raspbian and Useful Terminal Commands.

Requirements

• A Raspberry Pi running Raspberry Pi OS or an older Raspbian release.
• A network connection for the Pi, using Ethernet or Wi-Fi.
• A client computer on the same local network for the basic setup.
• The Pi's hostname or IP address.
• A local user account and password, or a configured SSH key.
• An SSH client. OpenSSH is normally available on Linux, macOS, and modern Windows. PuTTY is a graphical alternative for Windows.

You should understand basic usernames, passwords, administrator privileges, and local networking before proceeding. See Connect to the Internet if the Pi is not yet online.

SSH service status and defaults

SSH availability and default behavior vary between older Raspbian releases and current Raspberry Pi OS releases. Do not assume that SSH is enabled or that an old default username and password exist. Verify the service and explicitly enable it when necessary.

The OpenSSH server service is named ssh. From a local terminal on the Pi, check it with:

sudo systemctl status ssh

A running service normally shows an active state. If you need to enable it and start it immediately, use:

sudo systemctl enable --now ssh

Ways to enable SSH

Enable SSH with raspi-config

1. Open a terminal on the Raspberry Pi.
2. Run the configuration utility:

sudo raspi-config

3. Open the interface or service options.
4. Select the SSH option.
5. Choose to enable the SSH server and confirm the choice.
6. Exit the utility and verify the service:

sudo systemctl status ssh

SSH normally becomes available without a reboot. If it does not start automatically, run sudo systemctl enable --now ssh. More configuration utility guidance is available in Raspi Config.

Prepare a headless Pi before first boot

A headless Pi runs without a monitor or keyboard. The most reliable modern approach is to use Raspberry Pi Imager's OS customization settings before writing the storage card.

1. Choose the Raspberry Pi OS image and storage device in Raspberry Pi Imager.
2. Open the operating system customization settings.
3. Set a hostname.
4. Create a user account and choose a strong password.
5. Enable SSH and select password authentication or public-key authentication.
6. Configure Wi-Fi, locale, and wireless settings if Ethernet will not be used.
7. Write the image, insert the storage device into the Pi, and boot it.

Current Raspberry Pi OS images require a user account to be created before first login. Do not rely on a universal legacy default username or password.

For compatible image workflows, you can request SSH enablement by mounting the image's boot volume on another computer and creating an empty file named ssh. Do not add a filename extension. The boot partition's filename or mount label may differ between images and operating systems. This marker enables the service, but it does not replace the required first-user setup. Raspberry Pi Imager customization is preferred because it can configure the hostname, account, password, Wi-Fi, locale, and SSH together.

Find the Raspberry Pi on the network

Use a hostname

A hostname is a network name assigned to a device. If the local network and client support mDNS (multicast DNS), the Pi may be reachable as:

<hostname>.local

For example, if the configured hostname is mypi, try mypi.local. mDNS support is common but not universal, so use the IP address if name resolution fails. You can learn more about changing the device name in Change Raspberry Pi's Hostname.

Display the address on the Pi

From a local Pi terminal, run:

hostname -I

You can also inspect all interfaces and addresses with:

ip address

Check the router

Open the router's DHCP client or connected-device list and look for the Pi's hostname or hardware address. DHCP automatically assigns addresses, and an address can change after a lease expires or the Pi reconnects. For regular administration, consider a DHCP reservation in the router or a carefully configured static address.

Connect with OpenSSH

On Linux, macOS, or Windows with OpenSSH, use the configured username followed by the hostname or IP address:

ssh <username>@<hostname>.local

ssh <username>@<ip-address>

If SSH has explicitly been configured on a nonstandard port, specify it with -p. The normal SSH port is TCP port 22:

ssh -p <port> <username>@<ip-address>

At the first connection, the client displays the server's host-key fingerprint and asks whether to continue. A host key identifies the SSH server. Its fingerprint is a short representation used for verification. Accept the key only after confirming that the fingerprint belongs to the intended Pi, using a trusted local method where possible. Once accepted, the identity is saved in the client's known_hosts file.

Next, enter the Pi user's password, or let the client use the configured private key. A successful login opens a shell prompt. Confirm that the remote system is the Pi:

hostname && whoami

Connect with PuTTY on Windows

1. Open PuTTY.
2. Enter the Pi hostname or IP address in Host Name.
3. Set Port to 22, unless you explicitly configured another port.
4. Select SSH as the connection type.
5. Choose Open.
6. Review the first-connection host-key prompt and verify the fingerprint before accepting it.
7. Enter the Raspberry Pi username and password at the terminal prompts.

Basic remote administration

Commands typed in an SSH shell execute on the Raspberry Pi, not on the client computer. These safe checks show your identity, machine name, current directory, and files:

whoami
hostname
pwd
ls

sudo runs an administrative command with elevated privileges. Understand a command before using it, especially commands that delete files, modify networking, or change permissions. End the session with either command:

exit

logout

SSH security fundamentals

• Use a unique, strong password and do not retain known default credentials.
• For repeated access, prefer public-key authentication. The public key is installed on the Pi, while the private key remains on the client.
• Protect private keys with filesystem permissions and, where practical, a passphrase. Never share a private key.
• Generate an Ed25519 key pair on the client with:

ssh-keygen -t ed25519 -C "<client-label>"

Install the public key for the Pi user in /home/<username>/.ssh/authorized_keys with secure ownership and permissions. Test a new key-based login in a separate terminal before changing any server settings.

Only after key login works should you consider disabling password authentication in the SSH server configuration. Keep a working recovery method available so you do not lock yourself out.

• Restrict SSH exposure to trusted local networks where possible.
• Beginners should avoid forwarding port 22 directly from the public internet to the Pi.
• Changing the SSH port can reduce automated scans, but it is not a replacement for strong authentication and access controls.
• Keep Raspberry Pi OS and OpenSSH updated. See Update Raspbian for update fundamentals.

Transfer files with SFTP

SFTP, the Secure File Transfer Protocol, transfers files through the SSH service. It uses the same hostname or IP address, username, port, and authentication method as SSH, but it provides file operations rather than an interactive remote shell.

Start a command-line SFTP session with:

sftp <username>@<hostname-or-ip-address>

You can upload a file to the user's home directory, then use ls in the SSH session to verify it. The command-line scp tool and graphical clients such as WinSCP are other possibilities. See Use SFTP to Transfer Files.

Move from passwords to SSH keys

1. Generate an Ed25519 key pair on the client.
2. Install the public key in the Pi user's authorized_keys file.
3. Open a separate terminal and test a new SSH connection using the key.
4. Confirm that key login works after a new session and, if possible, after reconnecting.
5. Only then optionally disable password authentication.

Troubleshoot SSH connections

Start with physical and network checks: confirm that the Pi has power, its Ethernet or Wi-Fi connection is active, the client and Pi are on reachable networks, and the address belongs to the intended device. Check the router's DHCP list and try the IP address when hostname resolution is uncertain.

After a legitimate reinstall, remove the old client-side host-key entry with:

ssh-keygen -R <hostname-or-ip-address>

Do this only after confirming that the device really was reinstalled or replaced. A changed host key can be a warning that the address now belongs to a different device.

Headless login is unavailable

If a headless Pi boots but accepts no SSH connection, recheck that SSH was enabled during imaging or through the boot setup, that a user account was provisioned, and that Wi-Fi details are correct. Inspect the router's client list for an unexpected address. If necessary, connect a display and keyboard temporarily and inspect the network and ssh service locally.

Next steps

SSH is one form of remote access. For other options, see Access Raspbian Remotely, and review Display IP Address when locating the Pi. A DHCP reservation or static network configuration can make regular administration more predictable.