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.

Variable	Purpose	Platforms
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

Internal

Variable	Meaning	Default Value
DEFAULT_NET_WM_NAME	To change the window manager name, aka _NET_WM_NAME (see ticket:705#comment:10)	'Xpra'
NO_ROOT_WARNING	Skip warning if running as root	0
XPRA_USE_PROCESS_POLLING	Use process polling instead of relying on SIGCHLD	0
XPRA_POLL_DELAY	When using process polling, how often do we schedule it (in seconds)	2
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
STARTSTOP_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

Printing

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

Paths

Variable	Meaning	Default Value
DEFAULT_XPRA_CONF_FILENAME	Configuration 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_NVENC_DEBUG_API	Debug NVENC API calls	0
XPRA_CUDA_DEVICE	Cuda Device ID to use	-1 (first available)
XPRA_CUDA_DEVICE_NAME	Cuda device name to use (ie: "GTX 970")
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_OPENCL_YUV2RGB	Support YUV to RGB via OpenCL	0
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

Encoding

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
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

Sound

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_OPTIONS	Specify 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

X11

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_SUPPORTED	CSV 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_XSETTINGS_DEBUG	Debug XSettings	0
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
SOCKET_TIMEOUT	How long to wait before the initial connection times out	10
TCP_NODELAY	Use TCP no-delay	1
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
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

Crypto

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 seconds, every 10 seconds	0 (disabled)

MS Windows

Variable	Meaning	Default Value
XPRA_WIN32_WINDOW_HOOKS	Enable all window hooks	1
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_DPI_AWARE	Call SetProcessDPIAware| 1
XPRA_WIN32_MINMAXINFO	Enable MINMAXINFO workaround	1

Clipboard

Variable	Meaning	Default Value
XPRA_DISCARD_TARGETS	List of clipboard targets which are discarded
XPRA_TRANSLATEDCLIPBOARD_LOCAL_SELECTION	Default local selection for translated clipboard
XPRA_TRANSLATEDCLIPBOARD_REMOTE_SELECTION	Default remote selection for translated clipboard
XPRA_CLIPBOARD_LIMIT	Maximum number of clipboard transfers per second, clipboard will be disabled automatically beyond that	20