Raspberry Pi online course

Access a Raspberry Pi Desktop Remotely with xrdp

Learn how to install xrdp on Raspbian or Raspberry Pi OS and use Windows Remote Desktop Connection to control a Raspberry Pi desktop over a local network.

A remote desktop lets you view and control the graphical desktop of one computer from another. In this lesson, a Windows computer connects to a Raspberry Pi running Raspbian, also called Raspberry Pi OS on newer installations.

The Raspberry Pi must remain powered on and connected to the network. After the initial setup, you can use the Windows computer as the display, keyboard, and mouse, so the Pi can operate headless—without a permanently attached monitor, keyboard, or mouse.

How xrdp provides remote desktop access

xrdp is open-source server software that allows a Linux computer to accept connections using RDP, the Remote Desktop Protocol commonly used by Windows Remote Desktop Connection.

xrdp runs as a background service on the Raspberry Pi. It listens for RDP connections and creates a graphical desktop session after you authenticate with a Raspberry Pi user account. It is intended for graphical desktop access, rather than command-line administration alone.

For command-line administration, SSH may be more suitable. See how to enable SSH in Raspbian if you need terminal-only access.

Prerequisites

Prepare the following before installing xrdp:

  • A Raspberry Pi with Raspbian or Raspberry Pi OS installed and booted.
  • A desktop environment installed on the Pi. xrdp needs a graphical session.
  • A Raspberry Pi administrator-capable user account.
  • A local area network (LAN), such as the network provided by your home router.
  • A Windows computer connected to the same trusted LAN.
  • The Windows Remote Desktop Connection client. It is commonly launched with mstsc.
  • The Raspberry Pi's current local IP address.

A display, keyboard, and mouse may be needed for the first setup. You can instead perform the setup through SSH or another already-enabled administration method.

Remote access prerequisites

Powered Raspberry Pi: The Pi must be running and connected to power. Verify that it has booted normally.

Raspbian or Raspberry Pi OS desktop environment: xrdp provides a graphical session, so a desktop must be installed.

Local network connection: Both computers must be able to communicate on the same trusted LAN. Check their router or network connection.

Known Raspberry Pi IP address: Windows uses this address to locate the Pi. Display it with hostname -I.

Installed and running xrdp service: Check it with sudo systemctl status xrdp.

Windows RDP client: Start Remote Desktop Connection from the Start menu, Run dialog, or with mstsc.

Valid Raspberry Pi user credentials: Use the username and password of a real local account on the Pi.

Install xrdp on the Raspberry Pi

Open a terminal on the Raspberry Pi. You can use the desktop terminal, or connect through SSH if it is already enabled.

First refresh the package information. This helps the package manager use current information about available software.

sudo apt-get update

Install xrdp with the system package manager:

sudo apt-get install xrdp

Read the package prompt and confirm the installation when asked. The installation can add supporting components and normally registers xrdp as a system service.

Check the service:

sudo systemctl status xrdp

Look for an active or running state. If it is not running, enable it for future boots and start it now:

sudo systemctl enable --now xrdp

Run the status command again to confirm that the service is active.

Find the Raspberry Pi IP address

An IP address is the network address that identifies the Pi to other devices. Run:

hostname -I

The command may show one or more addresses. Choose the address belonging to the local network, often in a private range such as 192.168.x.x, 10.x.x.x, or 172.16.x.x through 172.31.x.x.

Do not use a loopback address such as 127.0.0.1. Loopback refers to the Pi itself and is not the address Windows should use.

You can also find the Pi in the router's connected-device list. DHCP, the service that automatically assigns addresses, may give the Pi a different address after a reboot or lease renewal. For regular access, create a DHCP reservation in the router. This maps the Pi's network adapter, usually by its MAC address, to a predictable LAN address.

For related address commands, see displaying the Raspberry Pi IP address.

Connect from Windows Remote Desktop Connection

  1. On Windows, open the Start menu and search for Remote Desktop Connection. You can also open the Run dialog and enter mstsc.
  2. In the Computer field, enter the Raspberry Pi's current IP address, such as 192.168.1.42.
  3. Select Connect.
  4. If Windows displays a certificate or identity warning, verify that the address belongs to the intended Raspberry Pi and that you are on your trusted local network. Then continue if the identity is expected.
  5. When the xrdp login screen appears, enter the Raspberry Pi username and password.
  6. Wait for the desktop session to load. A successful login shows the Raspberry Pi graphical desktop in the Windows window.

The Windows client and the xrdp login screen are separate stages: first Windows connects to the Pi's RDP service, then xrdp authenticates the Raspberry Pi account.

Credentials and account security

At the xrdp login screen, use the credentials for a local Raspberry Pi operating-system account. These are not necessarily the same as a Microsoft account used to sign in to Windows.

Do not retain default credentials on a networked Raspberry Pi. Change a default or weak password before relying on remote access:

passwd

Follow the prompts to set a strong, unique password. If several people need access, use separate user accounts rather than sharing one password. See how to change a Raspberry Pi password.

Use and manage the remote session

Once connected, use the Windows keyboard and mouse to operate applications, open files, and change settings on the Raspberry Pi desktop. Processing still occurs on the Pi; Windows displays the session and sends your input.

Closing the RDP window can disconnect the session. Depending on the desktop and xrdp configuration, applications may continue running, be closed, or behave differently when you reconnect. Save work before disconnecting, and use the desktop's normal logout option when you want to end the session completely.

Remote sessions can use a different resolution from a monitor attached directly to the Pi. If text or controls look too small, adjust the Remote Desktop Connection display settings before connecting. Scaling also depends on the Windows display and the Raspberry Pi desktop environment.

First-time local-network example

  1. Boot the network-connected Raspberry Pi and open its terminal.
  2. Run sudo apt-get update, then install xrdp with sudo apt-get install xrdp.
  3. Confirm the service with sudo systemctl status xrdp. If needed, run sudo systemctl enable --now xrdp.
  4. Run hostname -I and record the Pi's LAN address.
  5. On Windows, run mstsc and enter that address.
  6. Accept the expected identity warning only after checking that the address is the intended Pi.
  7. Sign in with a non-default Raspberry Pi user account and its strong password.
  8. Verify that the Raspberry Pi desktop appears and responds to the Windows keyboard and mouse.

Monitor-free workstation example

After testing the connection, place the Raspberry Pi wherever power and network connectivity are available, such as near the router. Keep it powered on, and use the Windows computer as its remote display and input device.

Create a DHCP reservation in the router so that the Pi usually receives the same LAN address. If you later cannot connect, check the router's connected-device list or run hostname -I locally to find the current address.

Verification and troubleshooting

When a connection fails, troubleshoot from the Pi toward Windows: confirm power, network reachability, the IP address, the xrdp service, credentials, and then the graphical session.

Common remote desktop issues

Connection cannot be established: The IP may be wrong, the Pi may be powered off or disconnected, xrdp may not be running, the networks may be isolated, or a firewall may block RDP traffic. Confirm the current address, verify both devices are on the same trusted LAN, and check sudo systemctl status xrdp.

Connection goes to the wrong device: A DHCP address may have been reassigned. Confirm the address in hostname -I or the router's device list, then use the corrected address.

Credentials are rejected: Enter the username and password for an existing Raspberry Pi account. Check whether the password was changed and reset it through an approved local administration method if necessary.

Blank or black desktop after login: This can indicate desktop-session incompatibility, a conflicting local graphical session, or an incomplete desktop or xrdp configuration. Restart the Pi and retry, install available system updates, confirm that a supported desktop environment is installed, and review xrdp and desktop-session logs.

Connection drops immediately: The graphical session may fail to start or may be incompatible with the installed desktop. Check the xrdp service and session logs, restart the Pi, and verify the desktop installation.

The Pi address changes later: DHCP may have assigned a new address after a reboot or lease renewal. Find the new address with hostname -I or the router's device list, then create a DHCP reservation.

Firewall and network isolation checks

If the Pi is running xrdp but Windows cannot reach it, check whether the computers are connected to separate networks, a guest Wi-Fi network, or a wireless network with client isolation enabled. Review firewall rules on the Pi and network equipment as appropriate. Only permit RDP traffic from trusted devices or networks.

Certificate warnings

xrdp can use a locally generated certificate that Windows does not already trust. A warning can therefore be normal on a first connection. Verify the target IP and local network before accepting it. An unexpected warning on an untrusted network should not be ignored.

Key points to remember

  • xrdp is an RDP server service for graphical Raspberry Pi desktop sessions.
  • The Pi must stay powered on and connected to the LAN.
  • Windows Remote Desktop Connection is launched with mstsc.
  • Connect to the Pi's current LAN IP address, not 127.0.0.1.
  • Use a real Raspberry Pi account and a strong, unique password.
  • A DHCP reservation makes repeated local access easier.
  • Restrict remote desktop access to trusted networks unless stronger network security is configured.

For background practice, review using the Raspbian terminal and connecting the Raspberry Pi to the internet.