XPRA(1)

📦
version 6.5.4 · 5 versions
, in fedora 43, fedora 44, nixpkgs unstable

💖 XPRA(1) — the general commands manual, but make it make sense 💖

okay bestie, listen — this is the manual page for xpra, aka your new favorite thing. It lives in the General Commands Manual section of the manual, and it is long, so buckle up. 🌈

✨ NAME ✨

xpra — viewer for remote, persistent X applications 🫶

🎀 SYNOPSIS 🎀

xpra seamless [CONNECTIONSTRING] | xpra desktop [CONNECTIONSTRING]
     [OPTIONS..]
xpra attach [CONNECTIONSTRING] [OPTIONS..]
xpra shadow [CONNECTIONSTRING] [OPTIONS..]
xpra proxy [:DISPLAY] [OPTIONS..]
xpra stop | xpra exit | xpra detach | xpra screenshot filename | xpra
     version | xpra info [CONNECTIONSTRING] | xpra id [CONNECTIONSTRING]
     | xpra top [CONNECTIONSTRING] [OPTIONS..]
xpra control [CONNECTIONSTRING] command [arguments..]  [--ssh=CMD]
     [--remote-xpra=CMD] [--socket-dir=DIR] [--socket-dirs=DIRS]
xpra displays [:DISPLAY]
xpra clean-displays [:DISPLAY]
xpra list [--socket-dir=DIR]
xpra list-sessions [--socket-dir=DIR]
xpra list-windows [--socket-dir=DIR]
xpra shell [CONNECTIONSTRING]
xpra showconfig [OPTIONS..]
xpra showsetting [SETTING1..]
xpra list-mdns
xpra docs
xpra html5
xpra upgrade [:DISPLAY] [...any options accepted by xpra seamless...]
xpra upgrade-desktop [:DISPLAY] [...any options accepted by xpra
     desktop...]
xpra recover [:DISPLAY] [...any options accepted by xpra seamless...]

🦋 DESCRIPTION 🦋

So here's the whole vibe: Xpra is a tool that lets you run X programs — usually on a remote host — and then beam their display straight to your local machine. And then?? You can disconnect from those programs and reconnect from the same machine or a completely different one, all without losing any state. No cap. 💅

The way it's different from standard X forwarding: it lets you disconnect and reconnect without disrupting the forwarded application. Iconic behavior.

And the way it's different from VNC and similar remote display techs: xpra can run rootless — meaning apps forwarded by xpra show up on your desktop as normal windows managed by your window manager, instead of being all "trapped in a box together". 🫶

Xpra also uses a custom protocol that is self-tuning and relatively latency-insensitive, which means it's actually usable over network connections that are too slow or unreliable for standard X forwarding. She's resilient, she's flexible, she ate. 🔥

Xpra can also be used to shadow an existing X11 display, or in desktop mode where it behaves more like VNC.

By default the Xpra server announces available sessions (username and display number) via mDNS to the local network. Use mdns=no to disable it. 📡

🌸 CONNECTION STRINGS 🌸

Xpra supports many types of connection strings (some may require extra packages to be installed):

💜 :DISPLAY[,OPTIONS]

Local displays: this is the simplest form and is only valid for the current local displays of the current user.

💜 tcp://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]

TCP mode uses port numbers and not display numbers. If multiple displays are available through a single TCP port (ie: using a proxy server), then one can also specify the display number after the port number.

💜 ssl://[[USERNAME][:PASSWORD]@]HOST:PORT[/DISPLAY][?OPTIONS]

SSL adds a secure socket layer on top of the TCP mode. 🔐

💜 vsock://[[USERNAME][:PASSWORD]@]HOST:PORT[/?OPTIONS]

Almost identical to the TCP mode, but using AF_VSOCK for transport.

💜 ws://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]

Connect using websocket protocol.

💜 wss://[[USERNAME][:PASSWORD]@]HOST:PORT/[DISPLAY][?OPTIONS]

Connect using secure websocket protocol. (websocket with SSL) 🔒

💜 ssh://[[USERNAME][:PASSWORD]@]HOST[:SSH_PORT]/[DISPLAY][?OPTIONS]

Connect using secure shell. (SSH)

Further SSH options can be specified using the --ssh command line option. The OPTIONS can be used to specify an ssh proxy: ?proxy=ssh://[USERNAME[:PASSWORD]@]HOST[:SSH_PORT] — xpra will then establish an SSH connection to the specified "proxy" host, and from that host xpra will set up an SSH connection to the xpra server. (proxy chain, we love a relay race 🏃♀️)

For backwards compatibility, SSH mode also supports the syntax: ssh:[USERNAME[:PASSWORD]@]HOST:DISPLAY but this form does not support specifying the SSH port number. Older versions also used the form protocol:host:port, but users are encouraged to move to a more standard URI format using :// as separator.

The password need only be specified when the server authentication module requires it.

💜 vnc://[[USERNAME][:PASSWORD]@]HOST[:VNC_PORT]/

Connect using the RFB protocol. (aka VNC) This mode only works against VNC servers or an xpra server in desktop or shadow mode.

⭐ EXAMPLES ⭐

  • xpra start :7 — Start an xpra server using display number :7.
Note: using DISPLAY=:7 xterm to start applications against a specific display is not recommended. Always prefer using xpra's --start= command line option instead. See this next example: 👇
  • xpra start --start=firefox — Start an xpra server, choosing a display automatically and start firefox on that virtual display. No window will appear until you attach with xpra attach. The start child commands will inherit an environment tailored for running under xpra. 🦊
  • xpra start ssh://bigbox/7 --start=xterm — Start an xpra server on bigbox with an xterm in it, and connect to it.
  • xpra desktop --start=xfce4-session — Start an xfce session in a nested X11 server on an automatically assigned display number.
  • xpra displays — Lists all the displays currently running on the system. This includes interactive desktop sessions as well as any virtual display (xvfb) whether or not they are being used by an xpra server. The displays in DEAD state can be recovered using xpra recover. 💀➡️✨
  • xpra clean-displays — Terminate any displays left in DEAD state.
  • xpra clean-sockets — Delete any server sockets belonging to dead servers.
  • xpra list — Show a list of xpra servers you have running on the current host. This will also run clean-sockets.
  • xpra list-sessions — Show a list of xpra servers, with extra information about each session if it can be collected.
  • xpra list-windows — Show a list of xpra servers you have running on the current host, including the session name and a list of windows. (only if the session can be queried using xpra info)
  • xpra list-mdns — Show a list of xpra servers found via mDNS. (local network) 📡
  • xpra docs — Open the documentation in a web browser. 🌐
  • xpra html5 — Open the html5 client in a web browser.
  • xpra shell — Start an interactive debug shell. 🐚
  • xpra showconfig — Shows the configuration that would be used with other sub-commands, taking into account the command line arguments.
  • xpra showsetting [SETTING1..] — Shows the value of a specific configuration setting and which configuration directory set this value.
  • xpra attach :7 — Attach to the xpra server that is using local display number :7. Any apps running on that server will appear on your screen. 🖥️
  • xpra attach ssh://foo@frodo/7 — Use ssh to attach to the xpra server that is running on machine frodo as user foo and using display :7. Any apps running on that server will appear on your local screen.
  • xpra start :7 --start=screen — Start an xpra server and a screen(1) session. If any of the applications inside screen attempt to use X, they will be directed to the xpra server.

🌈 DISPLAYS 🌈

Understanding the basic idea of displays is critical to using xpra successfully. Fr fr. Don't skip this part, bestie. 💅

The idea comes from standard X. If you have multiple X servers running on the same host, then there has to be some way to distinguish them. X does this by assigning each server a small, unique integer called (perhaps confusingly) its "display". In the common case of a desktop machine that has only one X server running, that server uses display :0 (or sometimes you'll see :0.0, which is effectively the same). When an application starts under X, it needs to know how to find the right X server to use; it does this by checking the environment variable $DISPLAY.

Xpra faces a similar problem — there may be multiple xpra servers running on the same host, as well as multiple X servers. It solves this problem by re-using X's solution — each xpra server has a display associated with it. This display functions as both an X display (for when xpra is talking to X applications) and as an identifier by which xpra clients (like xpra attach) can locate the xpra server. dual purpose, main character energy 👑

You may omit the display number when using xpra start: a display will be chosen for you automatically. The display number chosen will be shown in the log output, you should also be able to see it with xpra list. On Microsoft Windows and Mac OSX, the display number should be omitted.

Otherwise, when starting an xpra server, you may want to specify the name of the display to use. To do this, simply pick any number you like and stick a colon in front of it. For instance :7, :12, and :3117 are all valid display names. Just keep in mind that:

  • Every X or xpra server that is running on a single machine must use a different display name. If you pick a number that is already in use then xpra will not work. 😭
  • The first few numbers (0, 1, 2) are commonly used by real X servers.
  • Everyone who connects to a given machine using ssh(1) with X forwarding enabled will also use a display number; ssh generally picks numbers near ten (10, 11, 12, ...).

When specifying an xpra server to a client program like xpra attach, xpra detach, xpra stop, xpra exit, xpra version, xpra info, xpra list or xpra screenshot then you can use a display of the form :DISPLAY to refer to a server on the local host, or one of the form ssh://[USER@]HOST/DISPLAY to refer to a server on a remote host; xpra will automatically connect to the remote host using ssh(1). Generally, if you have only one xpra session running on a machine (which you can verify by running xpra list on that machine), then you can omit the number entirely; xpra attach alone will attach to the lone xpra server on the current machine regardless of its number, xpra attach ssh://frodo will similarly attach to the lone xpra session on a remote machine.

Connecting using the display number assumes that the client and server use the same configuration for socket directories, or at least that the client can find at least one of the directories used by the unix domain sockets (see bind, socket-dir and socket-dirs).

If the xpra server was given the --bind-tcp=[HOST]:PORT (or --bind-ssl, --bind-ws, --bind-wss, --bind-vsock) option when started then you can also connect to it using a display of the form tcp://HOST:PORT[/DISPLAY], ssl://HOST:PORT[/DISPLAY], ws://HOST:PORT[/DISPLAY], wss://HOST:PORT[/DISPLAY] or vsock://HOST:PORT[/DISPLAY]. 🎀

✨ SUBCOMMANDS ✨

okay bestie, these are the little spells you can cast with xpra. Each one is its own vibe. 💅

xpra start

This command starts a new xpra server, including any necessary setup. (When starting a remote server with the ssh://HOST/DISPLAY syntax, the new session will also be attached.)

xpra desktop

Starts a nested X11 server, all child commands will be started in the nested X11 server. 🖥️✨

xpra attach

This command attaches to a running xpra server, and forwards any applications using that server to appear on your current screen. basically your apps just pop up where you are 👑

xpra detach

Detaches the given xpra display. bye bye for now 🦋

xpra screenshot

Takes a screenshot and saves it to the filename specified. Note: screenshots can only be taken when a client is attached. 📸

xpra version

Queries the server version and prints it out. Note: older servers may not support this feature. ⭐

xpra connect-test

Tries to connect to a server to see if it is alive. This is normally even available prior to authentication. This command returns 0 if the server responded. 🔥

xpra id

Very similar to connect-test, but this subcommand also prints the basic server information it received: pid, uuid, etc 🆔

xpra info

Queries the server for full version, status and statistics. 📊

xpra top

Shows the server's key health attributes. vibe check for your server 🩺

xpra control

Modify the server at runtime by issuing commands. The list of commands can be obtained by specifying "help" as command. Some of those commands may support a "help" mode themselves. 🎛️

xpra initenv

This internal command creates the run-xpra script used with ssh connections. 🛠️

xpra stop

This command attaches to a running xpra server, and requests that it terminates immediately. This generally causes any applications using that server to terminate as well. 💀

xpra exit

This command attaches to a running xpra server, and requests that it terminates immediately. Unlike xpra stop, the Xvfb process and its X11 clients (if any) will be left running. 🚪

xpra showconfig

This commands shows the configuration which would be used given the arguments provided. You can also specify as extra arguments the specific options that should be displayed, or use the special value all to display all the options including the ones which are normally not displayed because they are not relevant on the given system. 🔍

xpra list

This command finds all xpra servers that have been started by the current user on the current machine, and lists them. 📝

xpra upgrade

This command starts a new xpra server, but instead of creating it from scratch, it attaches to another existing server, tells it to exit, and takes over managing the applications that it was managing before. As the name suggests, the main use case is to replace a server running against an older version of xpra with a newer version, without having to restart your session. Any currently-running xpra attach command will exit and need to be restarted. ⬆️

xpra upgrade-desktop

Same as upgrade but for servers started using desktop. It is possible to upgrade seamless server into a desktop server and vice versa. 🖥️⬆️

xpra recover

Similar to upgrade and upgrade-desktop: but without needing to specify if the server to recover is a seamless server or a desktop server. Unlike the upgrade subcommands, recover can also detect which displays need recovering. That is, displays which were previously used by an xpra server but this server has gone missing. 🩹

xpra shadow

This command shadows an existing display and is supported on X11, MacOS and MS Windows platforms. (this is not supported on Wayland yet) 😭

If there is only one X11 display active and its number is below 10, it can be auto-detected and the display may be omitted.

Note that this mode of operation uses screenscraping which is not very efficient. Video encoders partially mitigate this drawback.

By default, shadow mode will expose all the monitors connected as individual windows. But it is also possible to only shadow a specific region or monitor, or to group all monitors as a single window by specifying display options. Here are some examples:

To expose all monitors connected to display :1 as a single window, use the multi-window option:

xpra shadow :1,multi-window=no

To shadow a specific output using its name (ie: DP-1):

xpra shadow :1,DP-1

or more explicitly:

xpra shadow :1,plug=DP-1

To expose a rectangular area of size 1920x1080 as a single window, use:

xpra shadow :1,1920x1080

You may also want to specify the position of this rectangle (ie: 1280x0):

xpra shadow :1,1920x1080@1280x0

or using the more explicit syntax:

xpra shadow :1,geometry=1920x1080@1280x0

Multiple areas can be specified using / as separator, each one will be exposed as a separate window:

xpra shadow :1,1920x1080@1280x0/1280x600@0x400

xpra proxy

This command allows a single server to proxy connections for multiple others, potentially serving as a load balancing or authentication entry point for many sessions. The proxy server will spawn a new process for each proxy connection, this proxy process will create an unauthenticated new unix domain socket which can be used with the subcommands id, info, version and stop. 🌐

Important Note

Some platforms and package managers may choose to only build the client and not the server. In this case, only the attach subcommand will be available. so if you're missing stuff, that's why 🙈

🌸 OPTIONS 🌸

General options

  • --version — Displays xpra's version number. 🏷️
  • -h, --help — Displays a summary of command line usage. 🆘
  • --minimal — Disables all non-essential features. 🧘
  • -d FILTER1,FILTER2,..., --debug=FILTER1,FILTER2,... — Enable debug logging. The special value all enables all debugging. To get the full list of logging categories, run xpra -d help. To target loggers that use more than one logging category (as some categories can be quite broad), join them with a '+'. For example, to enable logging for server and keyboard, use --debug server+keyboard. You can also exclude a category with the '-' prefix. For example, to enable shadow debugging but not clipboard, use: --debug shadow,-clipboard. 🐛
  • --commands=yes|no — Enable or disable the ability to run commands on the server. Generally, clients expect to be able to request new commands to be executed by the server, but this can be turned off to securely lock down the server. 🔒
  • --shell=yes|no — Enable or disable the ability to connect to an xpra socket with the shell subcommand. This is useful for debugging and is not enabled by default. When disabled, it can still be enable on a per-socket basis using bind options. 🐚
  • --control=yes|no — Enable or disable the control channel of xpra sockets. This channel is accessed using the control subcommand to interact with an xpra process. 🎮
  • --mmap=yes|no|ABSOLUTEFILENAME|DIRECTORY — Enable or disable memory mapped pixel data transfer. By default it is normally enabled automatically if the server and the client reside on the same filesystem namespace. On MS Windows, clients do not enable it automatically: the server is very rarely running on the same host, and the memory is reserved before we can find out - use --mmap=yes to enable it explicitly. This method of data transfer offers much lower overheads and reduces both CPU consumption and local network traffic. When attaching, you can also specify an absolute path where the mmap file will be created. When used on the server, one can specify the exact filename that the client will create, or just the directory where the file will be created so that multiple clients may connect and use mmap concurrently. 🗺️
  • --mmap-group=GROUP — Sets the mmap file's gid to the group specified, and sets the permissions to 660. This is necessary to share the mmap file across user accounts. You can also use the special GROUP values:
    • no — Disable the functionality, the mmap file will use the default file permissions and default group ownership.
    • SOCKET — The group used will be the same one as found on the unix domain socket file the client connects to. Obviously, this can only work when connecting to unix domain sockets.
    • auto — Will use the 'xpra' group if the user is a member, otherwise it will fallback to the same behaviour as SOCKET.
  • --windows=yes|no — Enable or disable the forwarding of windows. This is usually the primary use for xpra and should be enabled. 🪟
  • --min-size=WIDTHxHEIGHT — Sets the minimum size for all decorated windows. 📏
  • --max-size=WIDTHxHEIGHT — Sets the maximum size for all windows. 📐
  • --readonly=yes|no — Read only mode ignores all keyboard and mouse activity. 🙅
  • --clipboard=yes|no|clipboard-type — Enable or disable clipboard synchronization. If disabled on the server, no clients will be able to use clipboard synchronization at all. If turned off on the client, only this particular connection will ignore clipboard data from the server. This can also be used to specify a different clipboard implementation. The clipboard types available will vary from platform to platform and also depend on build time environment and options so this is best left on auto. Other clipboard types available may include:
    • translated — Clipboard which can translate from one type of selection to another
    • GDK — The most complete clipboard implementation, includes full X11 support
    • default — Fallback clipboard, with limited X11 support
    • OSX — OSX specific clipboard
  • --clipboard-direction=to-server|to-client|both|disabled — Choose the direction of the clipboard synchronization. 🔄
  • --local-clipboard=SELECTION — Name of the local clipboard selection to be synchronized when using the translated clipboard. 📋
  • --remote-clipboard=SELECTION — Name of the remote clipboard selection to be synchronized when using the translated clipboard. 📋
  • --audio=yes|no — Enable or disable all audio support (both speaker and microphone forwarding). 🔊
  • --pulseaudio=yes|no — Enable or disable the starting of a pulseaudio server with the session. 🎧
  • --pulseaudio-command=SERVER-START-COMMAND — Specifies the pulseaudio command to use to start the pulseaudio server, unless disabled with pulseaudio=no. 🎵
  • --pulseaudio-configure-commands=COMMAND — the commands used to configure the pulseaudio server after it's already been started. You can specify this more than once, so go off bestie 💅
  • --video=yes|no — turn all video encoding support on or off. That's it, that's the whole vibe.
  • --video-decoders=DECODERS — says which video decoders get enabled. Use the special value help to get a list of options, iykyk.
  • --gstreamer=yes|no — enable GStreamer audio and video support ✨
  • --session-name=VALUE — sets the name of this session. This value may be used in notifications, utilities, tray menu, etc. Setting this value on the server provides a default value which may be overridden on the client. cute, right?
  • --encoding=ENCODING — sets the preferred encoding to use. To see the list of encodings available, use --encoding=help. This can be used to select grayscale or 8-bit modes like png/P. On local connections or with extremelly fast network links, plain rgb is also a viable option. For everything else, the default value auto will select the best encoding automatically and you should use the min-speed and min-quality options instead for tuning.
  • --encodings=ENCODING — this specifies the image encodings enabled. This is the most misused command line option and should be left alone. The server engine needs to have multiple encodings available to work effectively. like, hands off it, bestie 🙈
  • --video-scaling=on|off|SCALING — how much automatic video downscaling should be used, from 1 (rarely) to 100 (aggressively), 0 to disable. Video scaling is normally used with video regions or very large windows (especially full screen windows) to try to maintain a decent framerate. Video downscaling negatively affects visual quality and will cause automatic refreshes (if enabled), it is most useful on video content where it saves a considerable amount of bandwidth.
  • --socket-dir=DIR — location where to write and look for the Xpra socket files. The default location varies from platform to platform (~/.xpra and $XDG_RUNTIME_DIR/xpra on most Posix systems). If unspecified, the first value from socket-dirs will be used. It may also be specified using the XPRA_SOCKET_DIR environment variable.

When using the socket-dir option, it is generally necessary to specify socket-dir or socket-dirs on all following commands, for xpra to work with the open sessions.

By specifying a shared directory this can be coupled with the mmap-group and socket-permissions option to connect Xpra sessions across user accounts with shared memory acceleration. 👑

  • --socket-dirs=DIR — specifies the directories where to look for existing sockets if a specific one was not set using socket-dir. You may specify each directory using a new --socket-dirs command line argument, or joined together by the path separator (: on Posix). The paths will be expanded. (ie: --socket-dirs=~/.xpra:/tmp)
  • --sessions-dir=DIR — directory to place and look for the session files in. These files describe each running xpra session.
  • --system-proxy-socket=PATH — the socket path to use to contact the system-wide proxy server.
  • --file-transfer=on|off|ask — enable file transfers 🫶
  • --file-size-limit=SIZE — maximum size of file transfers (ie: 100M, 1G).
  • --open-files=on|off|ask — this option may be used to allow the remote end to automatically open files after they have been uploaded. This may be a security risk if you are using xpra to constrain what the clients can execute on the server. 🚨
  • --open-url=yes|no|ask — allow the remote end to ask for URLs to be opened on the local side. This may be a security risk.
  • --forward-xdg-open=on|off|auto — intercept execution of xdg-open and forward the request to the client.
  • --open-command=COMMAND — the command to use for opening files and URLs.
  • --printing=yes|no|ask — support printer forwarding from the server to the client.
  • --lpadmin=COMMAND — specify the lpadmin command to use when configuring forwarded printers.
  • --lpinfo=COMMAND — specify the lpinfo command to use when querying available printer drivers.
  • --bandwidth-limit=BITSPERSECOND — restrict bandwidth usage to below the limit given. The client's value cannot raise the limit of the server. The value may be specified using standard units, ie: 1Mbps or 500K. In auto mode, the client will set the bandwidth limit value to 80% of the maximum speed of the network interface it is using to connect to the server.
  • --bandwidth-detection=yes|no — automatically detect runtime bandwidth limits and adjust the encoding parameters accordingly.
  • --refresh-rate=VREFRESH — the vertical refresh rate to use, which is the target number of frames per second. The value may be specified in absolute form (ie: 60), as a percentage of the display's refresh rate (ie: 50%), or as auto to follow the display.
  • --reconnect=yes|no — automatically reconnect to the server if the connection is lost. the way that this just works 😭
  • --pings=SECONDS — how often to exchange ping and echo packets between client and server (in seconds, use zero to disable). The resulting latency statistics can be seen using xpra info.
  • --compressors=LIST — the packet compressors to enable, as a comma separated list (ie: lz4,brotli,none).
  • --packet-encoders=LIST — the packet encoders to enable, as a comma separated list (ie: rencodeplus,bencode).
  • --splash=yes|no|auto — show a splash screen during client or server startup. With the default value of auto, the splash screen is only shown if there is a GUI available - ie: no attempt will be made to show the splash screen when xpra is launched from an SSH session. 🎀

✨ Options for seamless, desktop, upgrade, proxy and shadow ✨

  • --daemon=yes|no — by default, the xpra server puts itself into the background, i.e. 'daemonizes', and redirects its output to a log file. This can be used to prevent that behavior (useful mostly for debugging).
  • --resize-display=yes|no|WIDTHxHEIGHT — resize the virtual display to match the resolution of the client currently connected. This only applies to the start and desktop subcommands. If a resolution is given, this will be the initial resolution of the display and the display will be resizable. A small set of pre-defined aliases can also be used: QVGA, VGA, SVGA, XGA, 1080p, FHD, 4K. ✨
  • --chdir=DIR — change to this directory after daemonizing.
  • --uid=UID and --gid=GID — when launching the server as root, these options can be used to drop privileges to the given UID / GID.
  • --pidfile=FILENAME — writes the server process ID to this file on startup. If the file has not been replaced, it will be deleted when the server exits.
  • --log-dir=DIR — the directory where server log files are placed when daemonizing.
  • --log-file=FILENAME — when daemonizing, this is where the log messages will go. If a relative filename is specified then it is relative to --log-dir. The value of $DISPLAY will be substituted with the actual display used.
  • --challenge-handlers=MODULE:options — configures which challenge handlers are used by the client and in which order. This option may be repeated to specify multiple handlers, which can be useful if the server sends more than one authentication challenge. The default value is: all which corresponds to: uri,file,env,kerberos,gss,u2f,prompt.
    • uri — use the password specified on the connection string, if any.
    • file — the filename used to store the password can be specified using the filename option. If this option is not specified, it will fallback to using the password filename specified with the password-file switch.
    • env — use the password specified using the environment variable specified using the name option, which defaults to XPRA_PASSWORD if unspecified.
    • kerberos — requests a kerberos token for the service specified.
    • gss — requests a gss token for the service specified.
    • u2f — requests a token from a U2F device.
    • prompt — prompt the user for the value. Terminal clients prompt using text input, GUI clients use a dialog.
  • --min-port=PORT — the minimum port number allowed when creating TCP sockets. You can use a lower value to allow unprivileged users to bind to privileged ports when starting sessions via the system wide proxy server. The default value is 1024 which is the standard value for privileged ports.
  • --mdns=yes|no — enable or disable the publication of new sessions via mDNS.
  • --dbus=yes|no|keep — enable or disable all dbus related functionality including dbus-launch, dbus-control and any feature that might use dbus. Use keep to preserve existing DBUS_* environment variables.
  • --dbus-launch=COMMAND|no — start the session within a dbus-launch context, you can specify the dbus launch command to use, or turn it off completely. Some features may not be available without a dbus context.
  • --dbus-control=yes|no — start a dbus server which can be used to interact with the server process.

🌈 Options for seamless, desktop, upgrade and listen: 🌈

In previous versions, the authentication for each connection type was configured using a separate command line option which would apply to all connections of the same type. ie: tcp-auth for bind-tcp. Although this is still supported as a fallback, the recommended way is to specify authentication options using bind properties. ie: bind-tcp=0.0.0.0:14500,auth=file,filename=password.txt. The properties can also define extra socket configuration options.

  • --bind=BIND_LOCATION[,PROPERTIES] — create a local Unix domain socket (on Unix) or named-pipe (on MS Windows) for each bind option specified.

This option can be specified multiple times to specify multiple socket locations. These sockets support local connections with the :7-style display address, and remote connections with the ssh://frodo/7-style display address. 💖

Local sockets may also process HTTP / Websocket connections if the html switch is enabled. 💖

The location can take the form:

  • none — do not create a socket (we simply vibe elsewhere 💀)
  • auto — backwards compatible default which uses the current socket-dir
  • DIRECTORY/ — create a socket in the directory specified, if the directory does not exist then it will be created - you should include the trailing slash to prevent the confusion with the PATH form:
  • PATH — create the socket using the path specified
  • --bind-tcp=[HOST]:PORT[,PROPERTIES] — Create a TCP socket for each --bind-tcp option specified. If the host portion is omitted, then 127.0.0.1 (localhost) will be used. If you wish to accept connections on all interfaces, pass 0.0.0.0 for the host portion.
Using this switch without setting the auth option is not recommended, and is a major security risk (especially when passing 0.0.0.0)! Anyone at all may connect to this port and access your session. Like, anyone. Bestie, please set auth. 🚨

TCP sockets may also process HTTP / Websocket connections if the html switch is enabled. TCP sockets may also be upgraded to SSL sockets if the ssl switch is enabled. ✨

  • --bind-ws=[HOST]:PORT[,PROPERTIES] — Create an HTTP / Websocket listener. See bind-tcp for host restrictions, you should use the auth-ws to secure access. 🔒
  • --bind-wss=[HOST]:PORT[,PROPERTIES] — Create an HTTPS / Secure Websocket listener. See bind-tcp for host restrictions, you should use the auth-wss to secure access. 🔐
  • --bind-ssl=[HOST]:PORT[,PROPERTIES] — Just like --bind-tcp but for SSL sockets. See ssl-auth and the other SSL options. 🌸
  • --bind-rfb=[HOST]:PORT[,PROPERTIES] — Listens for RFB connections on the given port. These sockets are only supported with the desktop and shadow modes. 👑
  • --bind-vsock=CID:PORT[,PROPERTIES] — Create a VSOCK socket for each --bind-vsock option specified. 🦋
  • --bind-ssh=[HOST]:PORT[,PROPERTIES] — Listen for connections using the SSH transport. See bind-tcp for host restrictions, use the ssh-auth option to secure access. 🎀
  • --bind-rdp=[HOST]:PORT[,PROPERTIES] — Listen for RDP connections. See bind-tcp for host restrictions, use the rdp-auth option to secure access. 🖥️
  • --bind-quic=[HOST]:PORT[,PROPERTIES] — Listen for QUIC HTTP/3 or WebTransport connections. See bind-tcp for host restrictions, use the quic-auth option to secure access. ⚡
  • --auth=MODULE[:OPTION=VALUE] — Specifies the authentication module to use for all unix domain sockets created using the bind switch. Authentication modules can validate a username and password against a variety of backend modules:
    • allow — always allows authentication - this is dangerous and should only be used for testing 🙈
    • fail — always fails authentication, useful for testing
    • env — matches against the environment variable specified by the name option (which defaults to XPRA_PASSWORD). ie: --auth=env,name=SOME_OTHER_ENV_VAR_NAME. 🌱
    • password — matches against the password specified using the value option. ie: --auth=password,value=YOURPASSWORD. Note: this command line option may be exposed to other processes on the same system. 😬
    • file — checks the password against the password data found in the file specified using the filename option. ie: --auth=file,filename=./password.txt.

The contents of this file will be treated as binary data, there are no restrictions on character encodings or file size. Beware of trailing newline characters which will be included in the password data. ⚠️ (yes, that sneaky \n counts as part of the password, no cap)

  • multifile — checks the username and password against the file specified using the filename option. The file must contain each user credentials on one line of the form:
username|password|uid|gid|displays|env_opts|session_opts

It is not possible to have usernames or password that contain the pipe character | which is used as delimiter, or newlines and carriage returns. This module is deprecated, sqlite should be used instead. 💀

  • sqlite
  • mysql
  • sql — checks the username and password against the sqlite database file specified using the filename option (for the sqlite backend), or the database specified using the uri option (mysql and sql backends). The authentication will be processed using the following query (which is configurable using the password_query option): SELECT password FROM users WHERE username=(?) The sessions available for each user will be queried using: (this is configurable using the sessions_query option): SELECT uid, gid, displays, env_options, session_options FROM users WHERE username=(?) Multiple displays may be specified as a comma separated list. 🗄️
  • hosts — checks the host using the system's tcp-wrappers library. (Posix only, and not available on Mac OS) See hosts.allow and hosts.deny for details. 🌐
  • exec — Executes the command specified using the command attribute, the arguments to this command are: a description of the access request and the timeout value. (also configurable) If the command is not specified, the system will try to locate and use the auth_dialog utility which is shipped with xpra. The command should return 0 to allow access, any other value will deny access. 🫡
  • peercred — checks the unix domain socket peer credentials using SO_PEERCRED. This authentication module is only available on some Posix compliant operating systems. This module will verify that the operating system provides the uid and gid of the process that initiated the connection. Access can be restricted by supplying a colon separated list of valid uids and gids that are allowed to connect. Those id values may be specified using numerical values or using the usernames / group names. This module is different from the others in that it will not require the client to supply a username or password, as those are ignored. Environment variables and pseudo-environment variables may also be used as values, eg: --auth=peercred,uid=\$UID:fred,gid=xpra. 🔍
  • pam — validates the username and password using the PAM system 🌸
  • win32 — validates the username and password using Microsoft Windows authentication (only available on this platform) 🪟
  • sys — chooses the appropriate system authentication module automatically (either pam or win32) 🤖
  • kerberos-password — validates the username and password using kerberos authentication. Warning: this module does not use kerberos tickets and the password will be sent in plain text to the server. This should only be used for testing. 🚨
  • kerberos-ticket — validates a kerberos ticket obtained by the client. 🎟️
  • gss — validates a GSS ticket obtained by the client. 🎫
  • u2f — requests a U2F token from the client. 🔑
  • ldap — validates the username and password against an LDAP server, using the python-ldap library. 📖
  • ldap3 — validates the username and password against an LDAP server, using the python ldap3 library. 📚
  • --tcp-auth=MODULE — Just like the auth switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch). Deprecated, use per-socket authentication options. 💅
  • --ws-auth=MODULE — Just like the auth switch, except this one only applies to ws sockets: sockets defined using the bind-ws switch, or TCP sockets upgraded to websockets. (if the html option is enabled). Deprecated, use per-socket authentication options. 💅
  • --wss-auth=MODULE — Just like the auth switch, except this one only applies to wss sockets: sockets defined using the bind-wss switch, ws sockets upgraded to SSL (if the ssl option is enabled) or TCP sockets upgraded to SSL and then to wss. (if both the ssl and html options are enabled). Deprecated, use per-socket authentication options. 💅
  • --ssl-auth=MODULE — Just like the auth switch, except this one only applies to SSL sockets: sockets defined using the bind-ssl switch, or TCP sockets upgraded by ssl=auto or ssl=on. Deprecated, use per-socket authentication options. 💅
  • --rfb-auth=MODULE — Authentication module to use for the bind-rfb sockets. Deprecated, use per-socket authentication options. 💅
  • --vsock-auth=MODULE — Just like the auth switch, except this one only applies to VSOCK sockets (sockets defined using the bind-vsock switch). Deprecated, use per-socket authentication options. 💅
  • --ssh-auth=MODULE — Just like the auth switch, except this one only applies to SSH sockets (sockets defined using the bind-ssh switch, or TCP sockets upgraded via the ssh-upgrade option). Deprecated, use per-socket authentication options. 💅
  • --rdp-auth=MODULE — Just like the auth switch, except this one only applies to RDP sockets (sockets defined using the bind-rdp switch, or TCP sockets upgraded via the rdp-upgrade option). Deprecated, use per-socket authentication options. 💅
  • --quic-auth=MODULE — Just like the auth switch, except this one only applies to QUIC sockets (sockets defined using the bind-quic switch). Deprecated, use per-socket authentication options. 💅

✨ Options for seamless, desktop, upgrade ✨

  • --exec-wrapper=CMD — A wrapper command which is prepended to all start commands. Typically, this is used for starting all sub-commands via VirtualGL. 🧚
  • --start=CMD — After starting the server, runs the command CMD using the default shell. The command is run with its $DISPLAY set to point to the newly-started server. This option may be given multiple times to start multiple commands. 🚀
  • --start-child=CMD — literally the same as --start, except the commands are taken into account by --exit-with-children. bestie behavior 💖
  • --start-late=CMD — like --start, but the command is only spawned once server initialization is complete. no rushing the server, periodt ✨
  • --start-child-late=CMD — like --start-child, but the command is only spawned once server initialization is complete. And yes, it is taken into account by --exit-with-children. late but still counted, iconic 💅
  • --start-after-connect=CMD — wait for the first client to connect before starting the command. it's giving patient main character energy 🦋
  • --start-child-after-connect=CMD — wait for the first client to connect before starting the child command. See start-child. same vibe, child edition 🌸
  • --start-on-connect=CMD — execute this command every time a client connects. every single time, no cap ⭐
  • --start-child-on-connect=CMD — execute this child command every time a client connects. See start-child. child command said "I'll be there" 🎀
  • --start-on-disconnect=CMD — execute this command every time a client disconnects. bye bye, run the thing 💜
  • --start-child-on-disconnect=CMD — execute this child command every time a client disconnects. See start-child. disconnect? child command clocked in ✨
  • --start-on-last-client-exit=CMD — execute this command every time a client disconnects and there are no other clients left. last one out, lights off, command goes brrr 🔥
  • --start-child-on-last-client-exit=CMD — execute this child command every time a client disconnects and there are no other clients left. See start-child. same energy, child command core 💖
  • --terminate-children=yes|no — on server stop, terminate all the child commands that have been started by the server. This does not affect server exit. Most child commands are tied to the display, so they are normally forced to shutdown anyway, but this gives them more time to cleanup properly and can be used to stop background commands that aren't tied to a display. cleanup era, we love to see it 🧚
  • --exit-with-children=yes|no — this option may only be used if --start-child is also given. If it is given, then the xpra server will monitor the status of the children started by --start-child, and will automatically terminate itself when the last of them has exited. my kids left, I'm out, fr fr 💅
  • --exit-with-windows=yes|no — the server will terminate automatically when there are no more windows or system trays being forwarded. This option is only relevant for seamless servers. seamless only, bestie, don't forget 🦋
  • --exit-with-client=yes|no — the server will terminate when the last client disconnects. last client said deuces 🌈
  • --env=KEY=VALUE — extra environment variables which will only affect commands started using --start or --start-child. only the start commands get these vibes ⭐
  • --start-env=KEY=VALUE — define environment variables used by commands started via --start and --start-child. May be specified multiple times. stack them like accessories 🎀
  • --source=FILE — shell script to source into the server environment before the server starts. May be specified multiple times. pre-game ritual for your server 💜
  • --source-start=FILE — shell script to source into the environment used for spawning --start and --start-child commands. May be specified multiple times. start commands get their own little source moment 🔥
  • --start-new-commands=yes|no — allow clients to ask the server to execute new commands. (this can also be used via the control channel) trusting the clients, okayyy 💖
  • --start-via-proxy=yes|no|auto — if enabled, the seamless and desktop subcommands will be delegated to the system wide proxy server instance. With auto mode, this delegation will only occur if the system wide proxy server is found. proxy said "I got this" ✨
  • --proxy-start-sessions=yes|no — use the proxy server to start new sessions. delegate, don't stress 💅
  • --systemd-run=yes|no|auto — wrap server start commands with systemd-run. systemd-run said come through 🦋
  • --systemd-run-args=ARGS — command line arguments passed to systemd-run. extra args, extra sparkle 🌸
  • --use-display=yes|no|auto — use an existing display rather than starting one with xvfb. You are responsible for starting the display yourself. This can also be used to rescue an existing display whose xpra server instance crashed or for running xpra against an accelerated X11 server. With auto, xpra will use the existing display if it is found. you're the display parent now, bestie 💜
  • --displayfd=FD — the xpra server will write the display number back on this file descriptor as a newline-terminated string. This is most useful when the display number is not specified with the xpra seamless or desktop subcommands. fd said "here's the number, write it down" ⭐
  • --xvfb=CMD — when starting a seamless server, xpra starts a virtual X server to run the clients on. If your Xvfb is installed in a funny location, or you want to use some other virtual X server, then this switch allows you to specify how to run your preferred X server executable. The default value used depends on your platform. The recommended command to use here is Xorg with the dummy driver, also known as Xdummy. See: https://github.com/Xpra-org/xpra/blob/master/docs/Usage/Xdummy.md Some distributions are unable to configure it properly and will use Xvfb instead. Xdummy is the moment, but Xvfb is the backup dancer 🔥
  • --sync-xvfb=DELAY — the windows are normally only displayed on the client(s), they are not painted on the virtual display. Some applications like screen recorders may want to capture the window contents, you can use this option to enable painting with a configurable delay (in milliseconds). Warning: this extra painting is expensive and quite slow, which is why it is not enabled by default. pretty but pricey, bestie 💀
  • --attach=yes|no|auto — once the server has started, immediately connect a client to it. With the value auto, a client is started for remote servers only. (servers specified via a network URI) If a display is specified and a server is already running, xpra will not try to start a new one and it will just attach to it. no duplicate servers, just attach and slay 🦋

✨ Options for seamless, desktop, upgrade, shadow ✨

  • --http=on|off — respond to HTTP requests on the TCP port(s) and local sockets. This requires at least one TCP or local socket to be configured using the matching bind option. HTTP said hi, but only if the bind option is set 🌸
  • --html=on|off|auto|webrootpath — this enables access to the html5 client via http. The auto mode will enable support if it is found. You can also specify your own web root path as argument. bring your own webroot, cute 💅
  • --http-scripts=off|all|SCRIPTS — enable the builtin web server scripts that expose the server status, current active sessions and displays, the list of applications and desktop sessions installed. This can be used by the client's user interface. scripts said "here's all the tea" 🎀
  • --rfb-upgrade=DELAY — allows RFB clients (ie: VNC) to connect to a plain TCP socket. If no data is received after DELAY seconds, the server will send a RFB handshake. This option is only applicable to servers started in desktop or shadow modes. VNC besties, this one's for you 💜
  • --ssl-upgrade=yes|no — upgrade WebSocket and TCP sockets to handle SSL connections. SSL glow-up 🔥
  • --websocket-upgrade=yes|no — upgrade TCP and SSL sockets to handle Websocket connections. websocket said let's upgrade the vibe 💖
  • --ssh-upgrade=yes|no — upgrade TCP sockets to handle SSH connections. SSH said I'm coming through ⭐
  • --rdp-upgrade=yes|no — upgrade TCP sockets to handle RDP connections. RDP upgrade era 💅
  • --video-encoders=ENCODERS — specifies the video encoders to try to load. By default, all of them are loaded, but one may want to specify a more restrictive list of encoders. Use the special value help to get a list of options. Use the value none to not load any video encoders. curate your encoder list, bestie 🦋
  • --csc-modules=MODULES — specifies the colourspace conversion modules to try to load. By default, all of them are loaded, but one may want to specify a more restrictive list of modules. Use the special value help to get a list of options. Use the value none to not load any colourspace conversion modules. colourspace modules, but make it a vibe check 🌸
  • --socket-permissions=ACCESS-MODE — specifies the file permissions on the server's unix domain sockets. Defaults to 600. This is ignored when mmap-group is enabled. permissions said 600, no cap 💜

🦋 Options for seamless, desktop, upgrade and attach 🦋

  • --encryption=CIPHER — specifies the cipher to use for securing the connection from prying eyes. This option requires the use of the --encryption-keyfile option. The only ciphers supported at present are:
    • AES — for servers, this allows the client to choose any of the modes it wants to use. For clients, this is an alias for AES-CBC and using a more specific mode should be preferred.
    • AES-CBC — AES in cipher block chaining mode
    • AES-GCM — AES in galois/counter mode
    • AES-CFB — AES in cipher feedback mode
    • AES-CTR — AES in counter mode

If the client requests encryption it will be used by both the client and server for all communication after the initial password verification, but only if the server supports this feature too. Note: this feature has not been extensively reviewed and as it is it should not be considered safe from determined attackers. secure-ish, but not "determined attacker" secure, bestie 😭

  • --tcp-encryption=CIPHER — just like the encryption switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch). TCP-only encryption, she's specific 💅
  • --encryption-keyfile=FILENAME — specifies the key to use with the encryption cipher specified with --encryption. The client and server must use the same keyfile contents. same key, same vibe, no mismatches 🔑
  • --tcp-encryption-keyfile=FILENAME — just like the encryption-keyfile switch, except this one only applies to TCP sockets (sockets defined using the bind-tcp switch). TCP keyfile said "I'm different" ✨
  • --idle-timeout=IDLETIMEOUT — the connection will be terminated if there is no user activity (mouse clicks or key presses) for the given amount of time (in seconds). Use the value 0 to disable this timeout. no clicks, no keys, no connection, periodt ⏳
  • --server-idle-timeout=IDLETIMEOUT — the server will exit if there are no active connections for the given amount of time (in seconds). Use the value 0 to disable this timeout. server said "nobody's here? I'm leaving" 🚪
  • --clipboard-filter-file=FILENAME — name of a file containing regular expressions, any clipboard data that matches one of these regular expressions will be dropped. Note: at present this only applies to copying from the machine where this option is used, not to it. clipboard filter said "not that, bestie" 🚫
  • --dpi=VALUE — the "dots per inch" number your client apps should try to respect 🎀. Keep it in the 10 to 500 range or it's basically useless. Heads up tho: a lot of apps only read this value at startup, so if you connect to a session that already got started with a different DPI, you might not get the glow-up you wanted 😭.
  • --pixel-depth=VALUE — okay so this one does two different jobs depending on what you're doing ✨. Starting a server? It controls the bits per pixel of the virtual framebuffer. Possible values: 0 (auto), 16, 24, 30. Starting a client? It controls the picture rendering with the opengl backend: values higher than 24 unlock deep color, while the value 24 gives you regular true color rendering. Use 0 to let the client decide whether the rendering would actually benefit from deep color (only supported on some Posix clients, no cap). Other values should not be used.
  • --cursors=yes|no — turns forwarding of custom application mouse cursors on or off 🖱️. Client apps can change the mouse cursor whenever they want, and every single time that happens the new cursor's pixels get sent over to the client. This switch kills that feature.
  • --notifications=yes|no — on/off for forwarding system notifications 🔔. These need the xpra server to have its own instance of a dbus daemon, and if it's missing you'll get a warning printed on startup. This switch disables the feature entirely and dodges that warning.
  • --input-method=METHOD — pick which input method to configure. This sets a bunch of environment variables that apps started with the start-child option should honour. The currently supported METHODs are:
    • none — disable input methods completely and stop them from interfering with keyboard input. This is the default.
    • keep — keeps the environment unchanged. You are responsible for making sure it's correct 💅.
    • xim — enables the X Input Method.
    • IBus — enables the Intelligent Input Bus.
    • SCIM — enables the Smart Common Input Method.
    • uim — enables the Universal Input Method.

Any other value will also be set up, but it'll trigger a warning ⚠️.

  • --xsettings=auto|yes|no — enable or disable xsettings synchronization. Xsettings only get forwarded from posix clients connecting to real posix servers (not shadows). In auto mode, only seamless servers enable xsettings synchronization.
  • --system-tray=yes|no — on/off for forwarding system tray icons 🧚. This one needs client support and might not even be available on every platform, iykyk.
  • --bell=yes|no — enable or disable forwarding of the system bell 🔔.
  • --webcam=yes|no — enable or disable webcam forwarding 📷.
  • --mousewheel=on|off|invert|invert-x|invert-y|invert-z — mouse wheel handling 🖱️. You can disable mouse wheel forwarding using the value no, or invert some or all of the axes: invert-all, invert-x, invert-y, invert-z.
  • --middle-click=yes|no — enable or disable forwarding of middle mouse button (button 2) events. Super useful for suppressing those spurious middle-click events that devices like the ThinkPad TrackPoint on Windows love to generate 🙈.
  • --pointer=on|off|emulate3buttons — how to handle pointer events. The emulate3buttons value will synthesize a middle-click whenever the left and right buttons get pressed at the same time ✨.
  • --input-devices=APINAME — which API to use for input devices on the server.
  • --keyboard-model=MODEL — the keyboard model to use on the server (passed to the X server) ⌨️.
  • --backend=NAME — which backend to use for accessing the display (ie: xvfb, xdummy).
  • --remote-logging=both|all|send|receive|no — remote logging is always initiated by the client, but the server gets to restrict which direction log messages are allowed to flow 📜.
    • both — the log output is both forwarded and sent locally (to stdout, stderr or a log file).
    • allow — used by the server to allow both send and receive, but when sending the log output it will no longer be recorded locally.
    • send — used by the client to send its log output to the server. Used by the server to allow clients to request log forwarding.
    • receive — used by the client to request that the server sends its log output to the client. Used by the server to allow clients to forward their logging.
    • no — remote logging is disabled.
  • --av-sync=yes|no — enable or disable audio-video synchronization 🎧📹. The video data gets delayed so it displays in sync with the audio. Note: this only applies to video regions, either auto-detected via the builtin heuristics or specified using the dbus interface.

✨ Options for attach ✨

  • --client-socket-dirs=DIR — directories where the client creates its control socket. The path separator (: on Posix) may be used to specify multiple directories 🗂️.
  • --modal-windows=yes|no — honour modal windows. Careful bestie, this can have undesirable side effects when multiple applications are forwarded through the same xpra server: modal windows get made modal for all the applications forwarded by xpra, not just the one application that owns that window 😬.
  • --headerbar=auto|no|force — replaces the window's standard title bar with a custom one that gives you access to xpra specific window controls 💅. This feature can have side effects and it is incompatible with OpenGL acceleration on MS Windows.
  • --password-file=FILENAME — supply the password to use for connecting to a server that uses authentication. > Deprecated, use per-socket authentication options instead.
  • --username=USERNAME — the username the client supplies for authentication. By default the current OS username is used.
  • --opengl=(yes|no|auto)[:backend] — use OpenGL accelerated rendering on the client ✨. The default is to detect whether the graphics card and drivers are supported (auto mode), but you can also disable OpenGL (no) or force it enabled (yes). On some platforms it's also possible to specify which backends should be used — only gtk and native are currently supported, and only on X11 platforms. ie: opengl=yes:native, or opengl=auto:gtk,native.
  • --webcam=yes|no|/dev/deviceXXX|DEVICEID — enable or disable webcam forwarding 📷. You can also specify the webcam device to use.
  • -zLEVEL, --compress=LEVEL — select the level of compression xpra will use when transmitting data over the network. There are only two possible values: 0 (meaning no compression) and 1 (compression enabled).

This compression is not used on pixel data (except when using the rgb encoding).

  • --quality=VALUE — sets a fixed image compression quality for lossy encodings (jpeg, webp, h264/h265 and vp8/vp9) 🎨. First, one of those lossy encodings must be enabled with --encoding or when using the default auto mode. Values range from 1 (lowest quality, high compression — generally unusable) to 100 (highest quality, low compression). Specify a value of zero to let the system tune the quality dynamically to achieve the best bandwidth usage possible. It's usually best not to use this option and use min-quality instead.
  • --min-quality=MIN-QUALITY — sets the minimum encoding quality allowed when the quality option is set to automatic mode. See quality above 👆.
  • --speed=SPEED — sets the encoding speed, from 1 (slowest) to 100 (fastest) 🏎️. Slower compresses better and will use less bandwidth; faster gives better latency as long as there's sufficient bandwidth. The system normally uses a variable speed, and this option forces a fixed speed setting to be used instead. It's usually best not to use this option and use min-speed instead.
  • --min-speed=MIN-SPEED — sets the minimum encoding speed allowed when the speed option is set to automatic mode. See speed above 👆.
  • --auto-refresh-delay=DELAY — sets a delay after which the windows are automatically refreshed using a lossless frame, if their contents had been updated using a lossy encoding previously ✨. The delay is a floating-point number and it's in seconds. This option is enabled by default with a delay of 0.25 seconds. It's only relevant when using a lossy encoding.
  • --shortcut-modifiers=MODIFIERS — defines the default shortcut modifiers required by the key-shortcuts, and these modifiers can then be referred to as #. The default value is 'auto' which evaluates to Meta+Shift on most platforms ⌨️.
  • --key-shortcut=KEY:ACTION — can be specified multiple times to add multiple key shortcuts 💅. These keys get caught by the client and trigger the action specified, and the key presses will not be passed on to the server.

The KEY specification may include keyboard modifiers in the form [modifier+]*key, for example: Shift+F10 or Shift+Control+B. You can refer to the shorcut-modifers option value using #, ie: #+F1.

Shortcuts defined on the command line are added to the builtin default shortcuts. To clear the list of shortcuts, use key-shortcut=clear and define your shortcuts after this one.

Some of the actions may allow arguments (ie: the log action does), in which case they are specified in the usual programming style syntax: ACTION(ARG1, ARG2, etc) String arguments must be quoted (both single and double quotes are supported) and numeric arguments must not be quoted. Beware the parenthesis and quotes must usually be escaped when used from a shell command line. Example: --key-shortcut=Meta+Shift+F7:log\(\'hello\'\)

The following ACTIONs are currently defined:

  • quit — disconnect the xpra client.
  • log("MESSAGE") — sends MESSAGE to the log.
  • show_session_info[("TabName")] — pops open the session info window. The optional TabName lets you pick which info tab gets shown, bestie. Just use the value help to get the whole list of options. ✨
  • show_menu — shows the menu you'd normally find hanging out in the system tray.
  • show_start_new_command — shows the start new command dialog.
  • show_shortcuts — shows the list of shortcuts. the receipts 💅
  • show_docs — shows the documentation in a browser window.
  • magic_key — a placeholder that some client toolkits can use. mysterious. iconic.
  • void — does not do anything, which is exactly why it's perfect for making sure certain key combos never, ever get sent to the server. 🚫
  • pass — also does nothing, BUT unlike void the key event is forwarded to the server. subtle, but it matters.
  • - — removes an existing key shortcut, if one exists.
  • refresh_window — forces the currently focused window to refresh.
  • refresh_all_windows — forces all the windows to refresh. every last one. periodt.
  • toggle_keyboard_grab — the keyboard will be grabbed / ungrabbed by the current window.
  • toggle_pointer_grab — the pointer will be grabbed and confined to the current window.
  • toggle_fullscreen — makes the current window fullscreen / unfullscreen.
  • toggle_debug — turns debugging on or off.
  • scaleup — increases the current value of desktop-scaling.
  • scaledown — decreases the current value of desktop-scaling.
  • scalereset — resets the desktop-scaling to its original value.
  • scalingoff — turns desktop-scaling off.
  • increase_quality — bumps up the min-quality or quality setting (whichever one is currently in use).
  • decrease_quality — brings the min-quality or quality setting down (whichever one is currently in use).
  • increase_speed — bumps up the min-speed or speed setting (whichever one is currently in use).
  • decrease_speed — brings the min-speed or speed setting down (whichever one is currently in use).
  • --sharing=yes|no|auto — sharing is what lets more than one client connect to the same session. Big catch though: it has to be enabled on both the server and all co-operating clients to actually work. When used server-side, the default value auto lets the clients decide whether they're willing to share the session. When used client-side, the default value auto evaluates to no.

To get sharing working with unix domain sockets (either using local connections or via ssh), you should create at least one socket in a group accessible directory. On Posix with a default configuration, being a member of the xpra group should be enough to create a socket in /run/xpra. You must also make sure the permissions of this socket file allow group access — see socket-permissions. 🫶

  • --lock=yes|no|auto — locking lets a client refuse to hand over the session to a new client. The session can still be shared with multiple clients (see the sharing option), but other than that, the server will reject new clients. When used server-side, the default value auto lets the clients decide if they want to lock the session. When used client-side, the default value auto evaluates to no.
  • --keyboard-sync=yes|no — normally key presses and key release events get sent to the server as they happen, so the server can keep a consistent keyboard state. Turning synchronization off can stop keys from repeating unexpectedly on high latency links — but it may also mess with applications that access the keyboard directly (games, etc.). 😭
  • --keyboard-raw=yes|no — tells the server to process all keyboard input untranslated. Both the client and the server must be using the same type of keyboard interface. (ie: both using X11)
  • --keyboard-backend=BACKEND — the keyboard backend is normally detected automatically. This option overrides it.
  • --keyboard-layout=LAYOUTSTRING — the keyboard layout is normally detected automatically. This option overrides it.
  • --keyboard-layouts=LAYOUTS — the list of keyboard layouts to enable.
  • --keyboard-variant=VARIANT — override for the keyboard layout variant.
  • --keyboard-variants=VARIANTS — override for the keyboard layout variants.
  • --keyboard-options=OPTIONS — override for the keyboard options sent to the server.
  • --swap-keys=YES|NO — this one only applies to MacOS clients. It swaps the command and control keys, and it's enabled by default. 🍓
  • --audio-source=PLUGIN — specifies the GStreamer audio plugin used for capturing the audio stream. This affects "speaker forwarding" on the server, and "microphone" forwarding on the client. To get a list of options, use the special value 'help'. You can also specify plugin options using the form:
--audio-source= pulse device=device.alsa_input.pci-0000_00_14.2.analog-stereo
  • --speaker=on|off|disabled and --microphone=on|off|disabled|on:DEVICE|off:DEVICE — sound input and output forwarding support, and here's how the values break down: on will start the forwarding as soon as the connection is established, off will require the user to enable it via the menu, and disabled will prevent it from being used at all and the menu entry will be disabled too. With microphone forwarding, you may also be able to specify which device to use. 🎀
  • --speaker-codec=CODEC and --microphone-codec=CODEC — specify the codec(s) to use for audio output (speaker) or input (microphone). This parameter can be specified multiple times, and the order in which the codecs are specified defines the preferred codec order. Use the special value 'help' to get a list of options. When unspecified, all the available codecs are allowed and the first one is used.
  • --title=VALUE — sets the text shown as the window title. The string you supply can make use of remote metadata placeholders, which get populated at runtime with values from the remote server. The default value used is "@title@ on @client-machine@". 🌈

The following placeholders are defined:

  • @title@ — will be replaced by the remote window's title.
  • @client-machine@ — will be replaced by the hostname of the system where the application is running, if provided, the xpra server's hostname otherwise.
  • @server-machine@ — will be replaced by the hostname of the xpra server.
  • @server-display@ — will be replaced by the name of the display on which the application is running.
  • --border=BORDER — specifies the color and size of the border to draw inside every xpra window. This is a vibe-check tool, fr: it makes it easy to tell xpra windows running on remote hosts apart from local windows. The BORDER can be specified using standard color names (ie: red, or orange) or using the web hexadecimal syntax (ie: #F00 or #FF8C00). The special color name "auto" will derive the color from the server target address (the connection string), so connecting to the same target should always give you the same color. You may also specify the size of the border in pixels, ie: --border=yellow,10.
  • --window-icon=FILENAME — path to the default image which will be used for all windows. This icon may be shown in the window's bar, its iconified state, or task switchers. It depends on the operating system, the window manager, and the application may override this too.
  • --window-close=ACTION — choose what action to take when the window is closed by the client. The following actions can be used:
    • auto — the client will figure out what's best based on the window type. This is the default. ie: it will use disconnect for shadow sessions, forward for seamless windows.
    • forward — the event will be forwarded to the server.
    • ignore — do nothing.
    • disconnect — disconnect from the server.
    • shutdown — shutdown the server.
  • --desktop-fullscreen=yes|no — when connecting to a desktop or shadow server, display the remote desktop fullscreen, scaling it to fit the local screen.
  • --dock-icon=FILENAME — path to the icon shown in the dock. This option only applies to macOS. 🍎
  • --desktop-scaling=off|on|auto|VALUE — desktop scaling lets the windows be scaled by the client. Quick tea: downscaling will mostly waste bandwidth, but upscaling lets the window's pixels be sent over the wire at a lower resolution, which saves bandwidth and CPU time. This option can also be used to request a specific scaling value. For best results, use opengl client rendering — the other display backends may show visual artifacts when scaling. Note: the scaling may also be adjusted at runtime through keyboard shortcuts, if those are configured. 💅

The desktop-scaling value can take the form:

  • off — scaling will be disabled.
  • on — scaling will be allowed, but it will start unscaled.
  • auto — scaling will be allowed and a scaling value will be automatically chosen if the client's desktop is large (bigger desktops will use higher scaling values).
  • scaling-value — scaling will be enabled and use the given value, specified as a number, fraction or percentage. ie: 2, 3/2 or 150%.
  • pair — the scaling will be enabled and use a different value for the X and Y axis. ie: 3x2 or 3/2x4/3.
  • desktop-size — the scaling will be enabled and the server will render to the given size. ie: 1600x1200.
  • --tray=yes|no — enable or disable xpra's own tray menu. On MacOS, the dock icon cannot be disabled. 🙈
  • --delay-tray — waits for the first window or notification to appear before showing the system tray. (posix only)
  • --tray-icon=FILENAME — tells xpra which icon to show in the dock/tray. If you don't say anything, it just uses a lil default 'xpra' icon. ✨ (Heads up bestie: on Microsoft Windows the icon has to be in ico format, no exceptions 💅)

🫶 Options for attach, stop, info, screenshot, version

  • --ssh=CMD — okay so when you connect to a remote display using an ssh: address, xpra literally runs ssh(1) to build the underlying connection. Most installations should be using paramiko as the default backend command nowadays. Other common values for CMD are ssh, or plink on Microsoft Windows. And if your ssh program lives somewhere weird, has a weird name, or you wanna pass special options to change how ssh behaves — that's exactly what --ssh is for, it tells xpra how to run ssh. 💖

For example, if you want arcfour encryption, you'd run:

xpra attach --ssh="ssh -c arcfour" ssh://frodo/7
Note: don't even bother enabling ssh compression, bestie — it's redundant with xpra's own compression and will just waste your CPU. 😭

On MS Windows, where backslashes separate path elements and spaces are often part of paths, you need to add quotes around paths. (ie: ssh="C:\Program Files\Xpra\Plink.exe" -ssh -agent)

  • --exit-ssh=yes|no — pick whether the SSH client process should get forcibly terminated when xpra disconnects from the server. If you're using SSH connection sharing, you might wanna avoid stopping the SSH master process instance that xpra spawned, since other SSH sessions might be using it. ⚠️ Note: exit-ssh=no detaches the SSH process from the terminal, which prevents the SSH process from interacting with terminal input — and that disables the keyboard interaction you need for password input, host key verification, etc.. 🫣
  • --remote-xpra=CMD — when connecting to a remote server over ssh, xpra needs to be able to find and run the xpra executable on the remote host. If that executable is in a non-standard location, or needs special environment variables set before it can run, then pulling this off may be non-trivial. So if xpra attach ssh:something fails because it can't find the remote xpra, you can use this option to specify how to run xpra on the remote host. 💅

That said — this option should not be needed in normal usage, because xpra tries quite hard to work around the above problems. If you find yourself needing it often, that may indicate a bug that we would appreciate hearing about. 🐛

🔒 SSL Options

  • --ssl=on|auto|off|tcp|www — whether to enable SSL on TCP sockets, and for what purpose. The TCP sockets will automatically be upgraded to SSL when SSL packets are received. 🌈
    • auto — the server will try to guess what protocol to use for each new SSL connection: either xpra's native protocol or https / websocket (wss)
    • tcp — the SSL sockets will only be used for xpra's native protocol
    • www — the SSL sockets will only be used for https and websocket (wss)

If SSL is enabled, then a ssl-cert is required. 🔥

The remaining options mirror the Python ssl module attributes. Please refer to that documentation, and bear in mind that configuring SSL for security is not trivial — and definitely not just a matter of enabling SSL. See: https://docs.python.org/2/library/ssl.html Some options may not be available with older versions of Python. 😬

Summary: --ssl-key=KEYFILE — the key file to use. 🗝️

  • --ssl-key-password=PASSWORD — password to use for decrypting the SSL key file.
  • --ssl-cert=CERTFILEORDIR — certificate file, required for server SSL support.
  • --ssl-protocol=PROTOCOLVERSION — specifies which version of the SSL protocol to use.
  • --ssl-ca-certs=CACERTSFILE — the ca_certs file contains a set of concatenated 'certification authority' certificates. If a directory is specified, it should contain the certificates.
  • --ssl-ca-data=CERTDATA — certificate data.
  • --ssl-ciphers=CIPHERS — sets the available ciphers, it should be a string in the OpenSSL cipher list format.
  • --ssl-client-verify-mode=none|optional|required — whether to try to verify the client's certificates and how to behave if verification fails.
  • --ssl-server-verify-mode=none|optional|required — whether to try to verify the server's certificates and how to behave if verification fails.
  • --ssl-verify-flags=FLAGS — the flags for certificate verification operations.
  • --ssl-check-hostname=yes|no — whether to match the peer cert's hostname.
  • --ssl-server-hostname=HOSTNAME — the server hostname to match against the certificate when connecting to an SSL server.
  • --ssl-options=options — set of SSL options enabled on this context.

🌸 ENVIRONMENT 🌸

  • DISPLAY — xpra start --start-child=... sets this variable in the environment of the child, pointing it at the xpra display. 🖥️

xpra attach, on the other hand, uses this variable to determine which display the remote applications should be shown on.

XPRA_PASSWORD may be used with xpra attach instead of the password-file option. 🔑 (iykyk, don't hardcode ur passwords bestie)

🎀 FILES 🎀

xpra.conf stores default values for most options. There's a global configuration file in /etc or /usr/local/etc, and each user may override those defaults by creating the file .xpra/xpra.conf. You can also split the options into multiple files by placing them in a conf.d directory with the .conf extension. Depending on OS and version, xpra uses the directory ~/.xpra or /run/<uid>/xpra to store a number of files. (The examples below are given for the display :7.) ✨

  • ~/.xpra/:7 — the unix domain socket that clients use to contact the xpra server, if the system configuration uses this directory.
  • ~/.xpra/:7.log — when run in daemon mode (the default), the xpra server directs all output to this file. This includes all debugging output, if debugging is enabled. 👀
  • ~/.xpra/run-xpra — a shell script that, when run, starts up xpra with the correct python interpreter, PYTHONPATH, PATH, location of the main xpra script, etc. Automatically generated by xpra initenv, xpra start, and used by xpra attach (see also the discussion of --remote-xpra). 🧚

💀 BUGS 💀

Xpra does not fully handle all aspects of the X protocol; for instance, fancy input features like pressure-sensitivity on tablets, some window manager hints, and probably other more obscure parts of the X protocol. It does, however, degrade gracefully, and patches for each feature would be gratefully accepted. 🫶 (not me volunteering y'all to send patches but like, pls do)

The xpra server allocates an over-large framebuffer when using Xvfb; this wastes memory. 😭 If the Xvfb does not support RandR this can also cause applications to misbehave (e.g. by letting menus go off-screen). This is not a problem when using Xdummy, see the --xvfb= switch for details. Conversely, if the framebuffer is ever insufficiently large, clients will misbehave in other ways (e.g., input events will be misdirected). 🙈

⭐ REPORTING BUGS ⭐

Send any questions or bug reports to https://github.com/Xpra-org/xpra/issues — they wanna hear from you fr fr. 🐛💖

👑 SEE ALSO 👑

and that's a wrap on the whole xpra(1) manual, bestie — every last flag, path, and caveat, no cap. this page is straight from the xpra manual, version XPRA(1), and yeah that footer is just the page name but we're giving it main character energy anyway. go forth and multiplex, you absolute icon 💅✨

📦 where this page comes from