---
title: Xpra
description: tmux/screen for X11
image: https://xpra.org/icons/xpra-logo.png
breaks: false
---

# Xpra -- tmux/screen for X11

<a href="https://github.com/Xpra-org/xpra/wiki">
<img alt="Xpra Wiki" style="display: block; margin: auto" src="https://xpra.org/icons/xpra-logo.png" />
</a>

[TOC]

## TL;DR

- Xpra makes GUI *persistent and detachable* whether *remote or local*.
It is to X11 what tmux and screen are to text terminals.
- Xpra combines the best of *X forwarding, VNC, and NX technology* on *a myriad of platforms*.
:::spoiler
- connection via TCP, SSL, SSH, (Secure) WebSocket, RFB, Unix domain socket, named-pipe (Windows), and vsock
- authentication/encryption via AES/SSL
- adaptive picture encoding and OpenGL acceleration
- connection multiplexing via proxy server, session sharing, and session broadcast via mDNS
- seamless/desktop mode
- audio/printer/webcam/keyboard forwarding
- clipboard/filesystem/tray/notification synchronization
- Fedora/RHEL/CentOS, Debian/Ubuntu, OpenSUSE, Windows, MacOS, or purely browser based
:::
- Read the [man page](https://xpra.org/manual.html).

## Architecture and Usage

Gathered from the [man page](https://xpra.org/manual.html), [Arch Wiki](https://wiki.archlinux.org/index.php/Xpra), and hands-on experience, here's my take on the matter.

- Installing Xpra gives one the command `xpra`.
The subcommand `xpra start` launches an *Xpra server* on some specified machine which I call the *server*; the machine from which one attempts to connect to the server via `xpra attach` is the *client*.
The server can be the same as the client.
The server must be a supported Linux distro with X11 installed; the client could be Linux, Windows, or Mac.
- Each user on the server can create several *Xpra sessions*.
Each of these Xpra sessions is a separate *Xpra server* managing an *X server*.
According to the [manual](https://www.x.org/releases/current/doc/man/man7/X.7.xhtml#heading5), each X server is referred to by a non-negative integer -- the *display number*.
Xpra borrows the notion by identifying each Xpra server with a unique [*display*](https://xpra.org/manual.html#DISPLAYS) which coincides with the display number of the X server it manages.
An Xpra server is operationally synonymous to an Xpra session to which the display also alludes.
- One can specify the server as an option of the `xpra` command; **omission implies the local machine**.
If the server is local, use the option `:DISPLAY` to specify display, e.g.,

    xpra SUBCOMMAND :DISPLAY

If display is unambiguous, `:DISPLAY` can be omitted.

If the server is referred by ssh, the command takes the form:

    xpra SUBCOMMAND ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT]/[DISPLAY][?QUERYSTRING]

- As usual, `SSH_PORT` is by default 22.
- Suppose `DISPLAY` is omitted.
If `SUBCOMMAND` is `start`, a valid `DISPLAY` will be automatically assigned; otherwise, the only possible `DISPLAY` is chosen if there is only one `DISPLAY` available on the server.
- `QUERYSTRING` is to specify [ProxyJump](https://man.openbsd.org/ssh#J), e.g.,

        ?proxy=ssh://[USERNAME2[:PASSWORD2]@]HOST2[:SSH_PORT2] 

The latest Xpra doesn't respect ssh config and keys, but it can be forced to by adding the option `--ssh=ssh`.
In this case, the following will work as expected given that `host` is defined in the ssh config.

    xpra SUBCOMMAND ssh://host/[DISPLAY] --ssh=ssh

Sample ssh config:

    Host host
        User USERNAME
        Hostname HOST
        Port SSH_PORT
        IdentitfyFile PRIVATE_KEY

### `xpra attach`

Attaches the specified display on the server to the client.
If no desktop environment is running in display, the attached windows will appear as if native; hence, the name *seamless mode*.
Otherwise, the whole desktop and its containing windows are forwarded much like VNC.
If an **`xpra attach` is interrupted by `ctrl-c`, the Xpra server is safely detached**, not stopped.

### `xpra detach`

Detaches the specified display on the server.
Suppose host is remote and client is local.
To detach, one issues the following, not just `xpra detach` locally.

xpra detach ssh://host/ --ssh=ssh

Equivalently, one can ssh into the server first, then, issue `xpra detach` in the remote shell.

### `xpra start` and `xpra start-desktop`

If the server is remote, it works as if one executed `xpra start` locally in the server, then, remotely attached to the server from the client.
The following shows serveral ways to start an Xpra session locally; adaptation for remote sessions are straight-forward.

- Starting a display with no windows:

    # xpra start :<display>
    xpra start :7

Then, applications can be associated with display afterwards:

    # DISPLAY=:<display> <app>
    DISPLAY=:7 xterm
    DISPLAY=:7 firefox

- Starting an application with an automatic display:

    xpra start --start=<app>

- Starting a whole desktop environment:

    xpra start-desktop --start=gnome-session

### `xpra list`

`xpra list` lists all Xpra servers on the specified server.
This command refers to servers not Xpra servers.

### `xpra info`, `xpra top`, `xpra version`, `xpra screenshot`

These commands refer to displays with functions most suggestive of their names.
Note that **screenshots can only be taken when a client is attached**.

### `xpra stop`, `xpra exit`, `xpra upgrade`, `xpra upgrade-desktop`

- `xpra stop` stops the specified Xpra server along with the X server it manages.
- `xpra exit` stops the specified Xpra server but not the X server it manages so that the windows in the display are kept running.
This subcommand is useful if one want to kill an unresponsive Xpra server that happens to contain a critical application that must be persisted.
- `xpra upgrade` replaces the specified Xpra server with a new Xpra server leaving the managed X server untouched.
This is useful for live updates of Xpra servers.
Note that **all Xpra servers will be detached** if previously attached to some client.
- `xpra upgrade-desktop` is the same as upgrade but for servers started using start-desktop.
The [manual](https://xpra.org/manual.html#:~:text=It%20is%20possible%20to%20upgrade%20seamless%20server%20into%20a%20desktop%20server%20and%20vice%20versa.) speaks of **interchanging seamless mode with desktop mode, but I don't know how**.

### Other Options

Xpra supports webcam/audio/filesystem forwarding and other fancy stuff.
I rarely need them, so I disable them in `~/.xpra/xpra.conf`.

pulseaudio=no
file-transfer=off
speaker=disabled
microphone=disabled
bell=no
printing=no
html=off
webcam=no
chdir=~/Desktop

These options could also be applied to individual `xpra` commands by prepending them with `--`.

## Installation

- [Download page](https://github.com/Xpra-org/xpra/wiki/Download)
- [Github wiki](https://github.com/Xpra-org/xpra/wiki)
- [Extensive documentation](https://github.com/Xpra-org/xpra/blob/master/docs/README.md)