xpra icon
Bug tracker and wiki

This bug tracker and wiki are being discontinued
please use https://github.com/Xpra-org/xpra instead.

The page has been moved to https://github.com/Xpra-org/xpra/tree/master/docs/Usage

Archived copy:

Getting Started : Usage

Here are just some of the most common usage scenarios:

See also, the manual. (this page is for the current development version, use man xpra to get the version corresponding to the version you have installed - *nix only..)
Note: we assume here that you have installed a supported and up to date version on both the client and the server. Some distributions ship outdated versions, do not use those.

Simple seamless application forwarding

As per the home page "get started" instructions, this is how xpra is most often used. This will start an xterm (or any graphical application you want) on SERVERHOSTNAME and forward it to your desktop:

xpra start ssh://SERVERUSERNAME@SERVERHOSTNAME/ --start-child=xterm

You can also execute each step individually:

  • on the server which will export the application (xterm in the example), start an xpra server instance on a free display of your choice (:100 in the example):
    xpra start :100 --start=xterm
  • then from the client, just connect to this xpra instance:
    xpra attach ssh://SERVERUSERNAME@SERVERHOST/100

(replace SERVERHOST with the hostname or IP of the server)
If you are attaching from the same machine as the same user and there is only one xpra session running, this is sufficient:

xpra attach
  • if the username is the same on the server, you can omit it
  • if there is only a single display in use (":100) you can omit it too

Access without SSH

SSH is great, it provides secure authentication and encryption, it is available on all platforms and is well tested.
However, in some cases, you may not want to give remote users shell access, or you may want to share sessions between multiple remote users.
In this case, use TCP sockets:

xpra start --start=xterm --bind-tcp=

Then, assuming that the port you have chosen (10000 in the example above) is allowed through the firewall (if any), you can connect from the client using:

xpra attach tcp://SERVERHOST:10000/

Beware: by default, TCP sockets are insecure. At the very least, you should use the "--tcp-auth=file,filename=mypassword.txt" option to protect those sessions. For more information see Authentication.

Forwarding a whole desktop

Xpra normally forwards just the windows of the application you are interested in. If you want to forward a full desktop instead (including its start menu, background, task bar, etc...) use the "start-desktop" mode:

xpra start-desktop --start-child=fluxbox


  • you can start a window manager of your choice (here fluxbox) or none at all..
  • to get the session to terminate when you exit the window manager, add --exit-with-children
  • beware: some desktop environments may show options to shutdown/reboot the system from their start menu, which may or may not be appropriate
  • you can resize the desktop using the standard "randr" desktop tools (and not by resizing the window at present)

Cloning / Shadowing an existing display

This allows you to access an existing desktop remotely. Simply:

xpra shadow ssh://SERVERHOST/


  • this also works for MS Windows and OSX, in which case the display argument is mostly meaningless (only used for naming the log file and identifying the session)
  • the display being shadowed must be active (not locked or turned off)
  • on posix systems, the default X11 session is usually :0 or :1 and should be detected automatically if there is only one active session
  • if there is more than one display active on the server system, you can specify which one you want to shadow: xpra shadow ssh://SERVERHOST/DISPLAY

Xpra as a clipboard sharing tool

Xpra can forward sound, clipboard and cursors as well as the application's windows. Each one of these feature can also be disabled, so one can use xpra as a clipboard synchronization tool:

  • From the client system:
    xpra shadow --no-printing --no-windows --no-speaker --no-cursors ssh://SERVERHOST/

(also disabling sound, printing, etc is not required)

Xpra as a printer forwarder

To forward a printer to another machine, simply start a remote session without starting an application, and ensure printer forwarding is enabled or force enable it on the command line:

xpra shadow --no-windows --no-speaker --no-cursors ssh://SERVERHOST/ --printing=yes

For more information, see wiki/Printing.

Last modified 16 months ago Last modified on 02/06/21 13:43:33