xpra icon
Bug tracker and wiki

Environment Options

This page lists some features which are often only available via environment variables, or where the environment variables override other options.

This list evolves constantly and should not be used as a definitive reference, only the source code for a particular version is.

There are also many environment variables which can be set for debugging, see wiki/Logging.

Unless the environment value is specified as being a number or a list, the possible values are:

  • 0 to disable
  • 1 to enable

No other values should be used (undefined behaviour).

Generic System Environment Variables

These variables may be defined by the system before xpra is launched.

PATH Locating executables All
HOME User UUID Posix
XDG_CURRENT_DESKTOP Detect the Ubuntu 'Unity' desktop Posix
LD_LIBRARY_PATH Locate wiki/FakeXinerama and other libraries Posix
DBUS_SESSION_BUS_ADDRESS Locate the dbus session server Posix
APPDATA Locate path to log files MS Windows
USERPROFILE Fallback code for locating download directory MS Windows


Variable Meaning Default Value
XPRA_NO_ROOT_WARNING Skip warning if running as root 0
XPRA_SKIP_UI Skip warnings, useful when running without a console 0
XPRA_FORCE_COLOR_LOG Force enable the coloured logger 0
XPRA_DETECT_MEMLEAKS Run memory leak detection code (expensive) 0
XPRA_DETECT_FDLEAKS Run file descriptor leak detection code (expensive) 0
XPRA_GRACE_PERCENT Percentage of the idle timeout before we enter the "grace" period 90
XPRA_LOG_PREFIX Prefix which is prepended to all log messages
XPRA_LOG_FORMAT Format used for all log messages %(asctime)s %(message)s
XPRA_PRINTER_RAW Allow "raw" printing 0
XPRA_PRINTING_PREFERRED_MIMETYPE Override the default order for mimetypes (normally "application/pdf" ahead of "application/postscript")
XPRA_UI_THREAD_POLLING How often to poll the UI thread (platform specific)
XPRA_MESSAGEBOX Show early command info and error messages using a dialog box on MS Windows 1
XPRA_WIN32_SEAMLESS Enable the experimental MS Windows seamless shadow server code 0

Client Options

XPRA_FAKE_BROKEN_CONNECTION Exercises the code normally firing when the server is not responding (ie: spinners), value in seconds - half on, half off 0
XPRA_PING_TIMEOUT How long to wait for a ping echo before disconnecting, in seconds 60
XPRA_UNGRAB_KEY Magic key which ungrabs the windows Escape
XPRA_AV_SYNC_DELTA Adjustment to the sound sync delay in milliseconds 0
XPRA_MOUSE_ECHO Request that the server forwards all mouse movements 0
XPRA_SHOW_SOUND_MENU Show the speaker and microphone tray menu entries 0
XPRA_SET_WORKSPACE Monitor for window workspace changes 1 (X11 only
XPRA_METADATA_SUPPORTED CSV list to request a more restricted set of window metadata from the server
XPRA_ALPHA Support transparency 1 (only on X11)
XPRA_OPENGL_DOUBLE_BUFFERED Use double-buffering 0 (1 on MS Windows)
XPRA_OPENGL_DEBUG Enable OpenGL debugging extensions 0
XPRA_OPENGL_PAINT_BOX Paint a coloured box around every screen update, size of the line in pixels (see #760) 0
XPRA_BOX_COLOR_$$$ Override the default colour for a specific encoding (PNG, RGB24, ..)
XPRA_ZEROCOPY_OPENGL_UPLOAD Enable zero copy texture uploads 1 if supported


XPRA_ADD_LOCAL_PRINTERS Allow local printers to be re-added (for testing) 0
XPRA_PRINTER_PREFIX Prefix prepended to printer names "Xpra:" when adding local printers only
XPRA_CUPS_DBUS Listen for cups event via dbus 1 (0 on OSX)
XPRA_CUPS_POLLING_DELAY How often to poll for cups printer changes (when not using dbus), in seconds 60
XPRA_SKIPPED_PRINTERS CSV list of MS Windows printer names which are not forwarded Microsoft XPS Document Writer,Fax
XPRA_DELETE_PRINTER_FILE Delete the temporary file 1
XPRA_PRINTERS_GENERIC Use generic printers found via lpinfo 1


Variable Meaning Default Value
XPRA_CONF_FILENAMEConfiguration file name 'xpra.conf'
XPRA_INITENV_COMMAND The command we run via ssh to ensure the environment is ready "xpra initenv"
XPRA_SYSCONF_DIR System configuration directory [*]
XPRA_SYSCONF_DIRS System configuration directories [*]
XPRA_USER_CONF_DIR User configuration directory [*]
XPRA_INSTALL_PREFIX Installation prefix [*]
XPRA_SOUND_COMMAND The command used for running the sound subprocess [*]
XPRA_FORWARDER_TMPDIR Temporary directory used by the xpraforwarder cups backend $TMPDIR or /tmp
XPRA_POSTSCRIPT_PPD PPD file to use for Postscript printing
XPRA_PDF_PPD PPD file to use for PDF printing

[*] the default is platform specific

Specific Encodings

Variable Meaning Default Value
XPRA_NVENC_VERSIONS Which versions of NVENC to try to load and in which order 4,5
XPRA_IGNORE_NVIDIA_DRIVER_BLACKLIST Ignore the builtin driver version blacklist 0
XPRA_NVENC_CLIENT_KEY Provide a client key for NVENC
XPRA_NVENC_PRESET Prefer a specific preset
XPRA_NVENC_YUV444_THRESHOLD Quality above which YUV444 mode is preferred 85
XPRA_NVENC_LOSSLESS_THRESHOLD Quality above which lossless mode is used 100
XPRA_CUDA_DEVICE Cuda Device ID to use -1 (first available)
XPRA_CUDA_DEVICE_NAME Cuda device name to use (ie: "GTX 970")
XPRA_PIL_DEBUG Enable Python Pillow debugging 0
XPRA_CODEC_SELFTEST Run self tests on start 1
XPRA_CODEC_FULL_SELFTEST Run full self tests on start (expensive) 0
XPRA_OPENCL_DEVICE_TYPE The type of device to use GPU
XPRA_OPENCL_DEVICE_NAME Select a specific device by name
XPRA_OPENCL_PLATFORM Select a specific OpenCL platform
XPRA_AMD_WARNING Show warning if the AMD OpenCL ICD is loaded 1
XPRA_CSC_CYTHON_$$$$$$$_COLORSPACES Restrict which format conversions are supported with the cython csc module (see ticket:937#comment:21)
XPRA_CSC_CYTHON_DEBUG_POINTS Debug colour for specific pixels with the csc cython module
XPRA_VP9_YUV444 Enable YUV444 mode with VP9 if available 1
XPRA_VP9_TILING Enable VP9 tiling support 0
XPRA_VPX_THREADS Number of threads to use with VP9 number of CPUs-1
XPRA_FORCE_SWSCALE Enable swscale with blacklisted versions 0
XPRA_X264_THREADS Number of threads to use with x264 0 (auto)
XPRA_X264_LOGGING x264 API logging level, supported values: ERROR,WARNING,INFO WARNING
XPRA_X264_LOG_NALS Log x264 NALs 0
XPRA_X264_OPENCL Use OpenCL if present 0
XPRA_X264_$$$$$$_PROFILE Profile to use for a given csc mode
XPRA_WEBP_LOG_CONFIG Log webp config used 0
XPRA_WEBP_THREADING Enable webp threading 1
XPRA_WEBP_IMAGE_HINT Default webp image hint graph
XPRA_WEBP_PRESET Default webp preset text
XPRA_WEBP_PRESET_SMALL Default webp preset for small areas icon


Variable Meaning Default Value
XPRA_FORCE_CSC_MODE Force the video pipeline to use a specific csc mode (ie: YUV420P)
XPRA_FORCE_CSC Force the video pipeline to use a csc step 0
XPRA_SCALING Support video scaling 1
XPRA_SCALING_HARDCODED Use a specific value of scaling (ie: 2/3)
XPRA_VIDEO_SUBREGION Support video regions 1
XPRA_SHADOW_REFRESH_DELAY How often the shadow servers poll the display for changes (in milliseconds) 50
XPRA_AUTO_REFRESH_THRESHOLD Quality above which we don't require a lossless refresh 100
XPRA_AUTO_REFRESH_QUALITY The quality used for lossless refresh 100
XPRA_AUTO_REFRESH_SPEED The speed setting used for lossless refresh 50
XPRA_MAX_PIXELS_PREFER_RGB The base level (adjusted at runtime) below which we prefer rgb encoding 4096
XPRA_DELTA Enable delta compression 1
XPRA_MIN_DELTA_SIZE Minimum size of the region to enable delta 1024
XPRA_MAX_DELTA_SIZE Maximum size of the region to enable delta 32768
XPRA_MAX_DELTA_HITS How many times do we use a delta region before recycling it 20
XPRA_MIN_WINDOW_REGION_SIZE Size below which we always send a full window update 1024
XPRA_ALPHA Enable transparency support 1
XPRA_FORCE_BATCH Always enable batching 0
XPRA_BATCH_$$$$ Tune specifc batch defaults
XPRA_ENCODING_STRICT_MODE Honour encoding specified stricly 0
XPRA_MERGE_REGIONS Try to merge paint regions to save CPU / bandwidth 1
XPRA_INTEGRITY_HASH Include an integrity hash with pixel packets 0

Client Decoding

Variable Meaning Default Value
XPRA_INTEGRITY_HASH Verify the integrity hash in pixel packets 0
XPRA_USE_PIL Use Python Pillow for decoding picture formats 1
XPRA_PIXMAP_INDIRECT_BGR Support slow BGR format with the pixmap backend 0
XPRA_SCALING_INTERPOLATION Type of interpolation to use when scaling (see gdkpixbuf.scale hyper
XPRA_USE_CAIRO_BACKING Prefer the cairo backing ahead of the pixmap backing 0
XPRA_DELTA_BUCKETS Number of delta bucket to use (see #756) 5
XPRA_WEBP_PILLOW Decode webp picture data using Pillow 0


Variable Meaning Default Value
XPRA_ALLOW_SOUND_LOOP Allow sound forwarding to/from the same system 0
XPRA_GSTREAMER1 Use GStreamer 1.x by default 1 (0 on win32 and osx)
XPRA_MONITOR_DEVICE_NAME Use a specific sound monitor device
XPRA_SOURCE_APPSINK The GStreamer sound capture element appsink name=sink emit-signals=true max-buffers=10 drop=true sync=false async=false qos=false
XPRA_SOUND_QUEUE_LEAK Controls if/how the queue element leaks (0=no leak, 1=leak upsteam, 2=leak downstream) 2
XPRA_SOUND_DEBUG Enable debugging for the sound subprocess wrapper 0
XPRA_SOUND_SUBPROCESS_DEBUG CSV list of debug flags to pass to the sound wrapper subprocess (ie network,util)
XPRA_SOUND_CODEC_ENABLE_$$$$$ Force enable a specific sound codec
XPRA_MUXER_OPTIONSSpecify which muxers are enabled as a CSV list gdp,ogg
XPRA_SOUND_SINK Default sound output plugin (platform dependent)
XPRA_SOUND_GRACE_PERIOD Ignore overruns and underruns during this grace period after startup (in milliseconds) 2000
XPRA_SOUND_MARGIN How much extra margin to keep in the sound buffer level (in milliseconds) 50


Variable Meaning Default Value
XPRA_X_SYNC Enable XSynchronize 0
XPRA_X11_PROPERTIES_IGNORED X11 properties we ignore as a CSV list "_NET_WM_OPAQUE_REGION"
XPRA_FORCE_REPLACE_WM Force an existing window manager to exit 0
XPRA_LOG_MANAGE_FAILURES Log all failures to manage a window 0
XPRA_NO_NET_SUPPORTEDCSV list of "_NET_SUPPORTED" items to remove from the default list we claim to support
XPRA_X11_DEBUG_EVENTS CSV list of X11 events to debug - typical values: KeyPress,ClientMessage ..
XPRA_REPARENT_ROOT Reparent windows to the root window, see #770 0
XPRA_X11_XKB Enable Xkb 1
XPRA_X11_XTEST Enable XTest 1
XPRA_X11_XFIXES Enable XFixes 1
XPRA_DEBUG_KEYSYMS Debug the key mapping for specific keys
XPRA_SHAPE_DEBUG Enable XShape debugging 0

Network / Connection

Variable Meaning Default Value
XPRA_SOCKET_HOSTNAME The name to use for the sockets the hostname
XPRA_SOCKET_TIMEOUT How long to wait before the initial connection times out 10
XPRA_PASSWORD Override the password file option
XPRA_ENCRYPTION_KEY Override the encryption key file option
XPRA_XSHM Enable XShm 1
XPRA_WRAPPER_DEBUG Debug the process wrapper 0
XPRA_HEXLIFY_PACKETS Dump the process wrapper's packets in hex form 0
XPRA_WIN32_SHOWWINDOW Run the process wrapper in a shell window on MS Windows 0
XPRA_USE_RENCODER Use rencode if available 1
XPRA_USE_BENCODER Use bencode if available 1
XPRA_USE_YAML Use yaml if available 1
USE_CYTHON_BENCODE Use the Cython version of the bencoder 1
XPRA_USE_ALIASES Use aliases for packet headers 1
XPRA_READ_BUFFER_SIZE Size of the network packet read buffer 65536
XPRA_PACKET_JOIN_SIZE Size below which packets and headers are joined up together same as read buffer size
XPRA_LARGE_PACKET_SIZE Size above which uncompressed data in packets triggers a warning 4096
XPRA_INLINE_SIZE Size below which compressed data is sent inlined in the main packet 32768
XPRA_MIN_COMPRESS_SIZE Size below which we don't try to compress the packet 378
XPRA_PROXY_SHOW_DATA Show data exchanged through the "xpra _proxy" hidden subcommand 0


Variable Meaning Default Value
XPRA_ENABLE_CRYPTO Enable encryption layer 1
XPRA_ENCRYPT_FIRST_PACKET Send the first packet encrypted (see #951) 0
XPRA_CRYPTO_DEFAULT_IV Override the crypto iv (default is random)
XPRA_CRYPTO_DEFAULT_SALT Override the crypto salt (default is random)
XPRA_CRYPTO_DEFAULT_ITERATIONS Override number of iterations 1000
XPRA_CRYPTO_INITIAL_PADDING Padding used in the initial packet (see #933) legacy
XPRA_CRYPTO_PREFERRED_PADDING Padding used (if supported) PKCS#7
XPRA_ALLOW_UNENCRYPTED_PASSWORDS Allow unencrypted passwords 0

Proxy Server

Variable Meaning Default Value
XPRA_PROXY_SOCKET_TIMEOUT Temporary socket timeout used by the proxy server during handover (in seconds) 0.1
XPRA_PROXY_QUEUE_SIZE Size of the internal queue buffers of each proxy instance 10
XPRA_PROXY_PASSTHROUGH Pass pixel packets straight through, unmodified 0

Fault Injection

For "rate" types of settings, the value is a number and specifies how often we simulate errors: a value of 10 will cause 1 error for every 10 events.

Variable Meaning Default Value
XPRA_PAINT_FAULT_INJECTION_RATE Simulate errors in paint events 0
XPRA_PAINT_FAULT_INJECTION_TELL Whether paint errors are reported back to the server 1
XPRA_WRAPPER_FAULT_INJECTION_RATE Simulate communication errors in the process wrapper 0
XPRA_PROTOCOL_FAULT_INJECTION_RATE Simulate network packet errors 0
XPRA_FAKE_JITTER Introduce jitter in the network layer (value in milliseconds) 0
XPRA_SIMULATE_SERVER_HELLO_ERROR Simulate errors in the server's hello packet handlers 0
XPRA_SOUND_FAULT_INJECTION_RATE Injects invalid data into the sound subprocess's "info" packet output 0
XPRA_SOUND_FAKE_START_FAILURE Causes the sound subprocess to fail to start 0
XPRA_SOUND_FAKE_EXIT Causes the sound subprocess to exit cleanly after the given delay (in seconds) 0 (disabled)
XPRA_SOUND_FAKE_CRASH Causes the sound subprocess to crash after the given delay (in seconds) 0 (disabled)
XPRA_FAKE_UI_LOCKUPS Simulate UI thread lockups for the given number of milliseconds, every 10 seconds (was measured in seconds before r10659, in 0.15.x and earlier) 0 (disabled)

MS Windows

Variable Meaning Default Value
XPRA_WIN32_WINDOW_HOOKS Enable all window hooks 1
XPRA_WHEELEnable mouse wheel speed window hook workaround 1
XPRA_WHEEL_DELTAMouse wheel acceleration for workaround 120
XPRA_WIN32_GROUP_LEADER Enable group leader workaround 1
XPRA_WIN32_UNDECORATED_STYLE Enable undecorated style workaround 1
XPRA_WIN32_MAX_SIZE_HINT Enable max size hint 1 (0 with gtk3)
XPRA_WIN32_GEOMETRY Geometry workarounds 1
XPRA_WIN32_CLIP_CURSOR Support for clipping the cursor (grabs) 1
XPRA_DPI_AWARE Call SetProcessDPIAware (see #163) 1
XPRA_DPI_AWARENESS Call SetProcessDPIAwareness (see #163) 1
XPRA_FORWARD_WINDOWS_KEY Forward the special "Windows" key 1
XPRA_WIN32_LANGCHANGE Detect keyboard language changes 1


Variable Meaning Default Value
XPRA_DISCARD_TARGETS List of clipboard targets which are discarded
XPRA_CLIPBOARD_LIMIT Maximum number of clipboard transfers per second, clipboard will be disabled automatically beyond that 20
Last modified 2 months ago Last modified on 01/12/17 10:07:57