Encodings

August 7, 2026 · View on GitHub

Xpra supports a wide variety of picture and video encodings for sending window contents to the client quickly and efficiently. For background information on picture encodings, see images.guide.

Choosing an encoding is best left to the Xpra engine. It considers the window’s characteristics, network performance, user preferences, client and server capabilities, and available processing power.

If tuning is needed, use min-speed and min-quality before overriding the encodings or encoding options. The xpra configure encodings tool is designed to help with this; use it first and try other options only later.

Available encodings

These encodings control how Xpra selects and compresses screen updates.

Pseudo encodings

Pseudo encodings control which actual encodings the engine may select:

  • auto — the default; allows all options
  • grayscale — allows all options without sending colours, which can save bandwidth
  • scroll — tries harder to send screen updates using motion vectors; see the scroll encoding for the semantics client implementations must honour

Select one with --encoding=ENC.

Local and raw pixels

  • mmap — all bit depths; fastest; only available with local connections and selected automatically
  • rgb — all bit depths; very fast; raw RGB pixels, potentially compressed with a stream compressor such as lz4

Compressed picture encodings

  • webp — 24 / 32 bit; good; fast, with transparency and lossy or lossless modes
  • jpeg — 24 bit; fast and easy to support
  • avif — 24 bit; average; limited support
  • png — 24 / 32 bit; slow and easy to support
  • png/P — 8 bit; slow; useful for 8-bit desktop mode
  • png/L — 8 bit; slow; greyscale

Video encodings

Video streams are often the most efficient way to send large amounts of screen updates without consuming too much bandwidth. Xpra automatically detects when switching to a video codec makes sense.

VP8 and VP9

  • vp8 — 24 bit; fast but less efficient
  • vp9 — 24 / 30 bit; more efficient but somewhat slower

H.264 and HEVC

  • h264 — 24 / 30 bit; licensing issues
  • hevc — 24 / 30 bit; licensing issues and usually slower

AV1

av1 supports 24-bit colour. It is the most efficient video encoding, but does not provide a lossless mode.

Video encoders

Xpra ships these encoder modules. Availability and supported encodings can vary with the Xpra version, build options, and hardware capabilities.

  • vpx — vp8, vp9
  • x264 — h264; fast
  • nvenc — h264, hevc, av1; fastest, requires hardware

Choose which modules are loaded at runtime with video-encoders.

Colorspace conversion

Some video encoders require a colorspace conversion step. These modules can:

  • convert pixels received by the server into a format consumed by video encoders
  • convert decoded pixels into a format that can paint the client window
  • scale pixels up or down when needed

Available modules include:

  • cython — r210, BGR48, GBRP10, YUV444P10; slow but useful for high-bit-depth modes
  • libyuv — BGRX, YUV420P, NV12; fastest

Choose loaded modules at runtime with csc-modules.

Video decoders

Xpra ships these decoder modules:

  • openh264 — h264
  • vpx — vp8, vp9
  • aom — av1

Choose which modules are loaded at runtime with video-decoders.

Diagnostics

Use these commands to see which encodings, codecs, and conversion modules are available in the current installation.

List available encodings

xpra encoding

On Windows and macOS, you can also use the Encodings_info wrapper.

List video codecs and conversion modules

xpra video

List client encodings

xpra attach --encoding=help

List server encodings

xpra seamless --encoding=help

Enable encoding debug logs

xpra seamless -d damage,compress,encoding

Tuning

Tuning is often misused and can make performance worse. Start with the automatic selection and minimum quality or speed settings before forcing a specific encoding.

Prevent blurry screen updates

Rather than selecting a lossless picture encoding, which may use too much bandwidth and cause performance issues:

  • make sure applications are detected correctly using the content-type and content-categories mappings
  • raise min-quality and/or lower min-speed
  • consider lowering the auto-refresh delay, while remembering that lossless refreshes can be costly

Quality

Values range from 1 (lowest) to 100 (lossless). Rather than tuning quality, use min-quality. Lower values save bandwidth and CPU but may make updates more blurry.

Speed

Values range from 1 (lowest) to 100 (lossless). Rather than tuning speed, use min-speed. Lower values use more CPU, reducing bandwidth consumption but possibly lowering the framerate.

Best performance

Use NVENC or another hardware encoder supported by libva when available. Hardware encoders compress very well and do so extremely quickly.

Further reading

When comparing performance, use the right metrics. Updates per second (fps) are not always meaningful: many small regions can make a high or low count misleading.