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.

HOME	User UUID
XDG_CURRENT_DESKTOP	Detect the Ubuntu 'Unity' desktop
LD_LIBRARY_PATH	Locate wiki/FakeXinerama and other libraries
DBUS_SESSION_BUS_ADDRESS	Locate the dbus session server

Internal

Variable	Meaning	Default Value
DEFAULT_XPRA_CONF_FILENAME	Configuration file name	'xpra.conf'
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
INITENV_COMMAND	The command we run via ssh to ensure the environment is ready	"xpra initenv"
XPRA_USE_PROCESS_POLLING	Use process polling instead of relying on SIGCHLD	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

Specific Encodings

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

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

X11

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

Network / Connection

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

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

Proxy Server

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.

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

Clipboard

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