WSLg Clipboard Integration: Trace Copy and Paste Across the GUI Boundary

Copy and paste in a WSL session can refer to two separate systems. Windows Terminal has its own text selection and clipboard commands for a terminal buffer. A Linux GUI application launched through WSLg uses a Linux display protocol and the WSLg remoting integration. A successful paste in a terminal tab does not prove the GUI clipboard path works, and a GUI application copying text does not test the terminal’s selection behavior.

Microsoft’s WSLg project documents clipboard integration as part of its enhanced Weston RDP backend. WSLg runs the graphical integration in a system distribution and exposes the GUI service to user distributions. The clipboard path therefore crosses application selection handling, the Linux display stack, WSLg’s compositor/RDP integration, and the Windows host. Diagnose the intended application and selection protocol, not just whether some other copy shortcut works.

Identify which clipboard the user is testing

Write down the exact source and destination. Is the source a Windows Terminal selection, an X11 application, a Wayland application, a browser running in WSLg, or a Windows editor? Does the destination use the primary selection, the clipboard selection, or the terminal’s own copy action? The answer changes which component is responsible.

X11 distinguishes the primary selection from the CLIPBOARD selection. Wayland clients use compositor-mediated data offers and protocol extensions. Many applications map Ctrl+C and Ctrl+V to a clipboard action while mouse selection may use another selection. This can create a symptom where keyboard copy works but middle-click paste does not, or one Linux application can paste from another while Windows cannot. Such a result narrows the protocol boundary rather than proving that WSL networking or the distro filesystem is involved.

The WSLg system distribution and the user distro are also distinct environments. User applications connect to the WSLg-provided display endpoints through projected sockets and environment variables. Do not install another compositor or overwrite DISPLAY and WAYLAND_DISPLAY as a generic clipboard repair; that can redirect the application away from the WSLg path being tested.

Capture the display session and versions

From a Linux GUI application’s launching shell, capture the environment and endpoint availability:

printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\nXDG_RUNTIME_DIR=%s\n' \
  "$DISPLAY" "$WAYLAND_DISPLAY" "$XDG_RUNTIME_DIR"
case ${WAYLAND_DISPLAY:-} in
  /*) test -S "$WAYLAND_DISPLAY" && echo "Wayland socket present" ;;
  *) test -n "${XDG_RUNTIME_DIR:-}" &&
       test -S "$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY" && echo "Wayland socket present" ;;
esac
find /mnt/wslg -maxdepth 3 -type s -print 2>/dev/null | head

The exact socket path can vary with the runtime setup, and X11 applications may use XWayland instead of connecting as native Wayland clients. Treat the variables as clues, not as a checklist requiring every application to use both servers. Record the output alongside Windows build and wsl.exe –version, then reproduce in a fresh GUI application process.

When copy works in one application and fails in another, compare how each application was launched, which display protocol it selected, and whether it runs in a sandbox or container. A process launched from a terminal inherits that shell’s environment. A Start Menu entry can use WSLg’s application integration path and have a different environment context. Keep those launch paths separate during diagnosis.

Test a controlled clipboard transfer

Install the clipboard command-line utilities appropriate to the active display server. For Wayland, wl-clipboard provides wl-copy and wl-paste. For X11, common utilities include xclip or xsel. Their existence does not prove that an application chose the corresponding display protocol. Use a short non-sensitive marker rather than a password, token, or private document:

printf 'wslg-clipboard-probe-2026-10-03' | wl-copy
wl-paste --no-newline

A successful round trip tests a Linux client talking to its display clipboard selection. It does not by itself prove that the Windows host received the selection. Open a Windows text editor and paste the marker, then copy a different marker from Windows and paste it into a Linux GUI application. Test both directions and both source applications separately.

For X11 applications, choose the selection explicitly in the tool rather than relying on its default. Compare CLIPBOARD and PRIMARY behavior. If the Linux-side round trip works but Windows cannot paste, the application and local selection path are likely functioning; investigate WSLg’s remoting integration and version. If neither Linux application can exchange text, start with the client protocol, socket, environment, and app sandbox.

Separate terminal copy from GUI clipboard

Windows Terminal usually handles selecting text in its own terminal surface and offers its own keyboard shortcuts and settings. The shell process inside that tab does not own the terminal’s scrollback selection. A Linux GUI window uses WSLg’s GUI integration instead. Therefore, validate a terminal selection by copying output from the terminal buffer into a Windows app, then validate a WSLg GUI selection by copying text inside a Linux GUI window into the same Windows app.

The terminal emulator can also send a key sequence to the shell or foreground program. In a full-screen terminal editor, Ctrl+C may mean an application command or an interrupt depending on the program and mode; it is not necessarily a clipboard command. Use the terminal’s configured copy action or context menu when testing terminal buffer copy. Do not diagnose Linux PTY signal handling from a GUI clipboard test.

Use WSLg diagnostics only after capturing a baseline

The WSLg repository describes its architecture and the components involved in window remoting and clipboard integration. Its debugging wiki documents optional clipboard-related logging and switches in WSLg configuration. These are product diagnostics, not standard per-distro settings. Capture the default behavior first, then enable documented temporary diagnostics only when the symptom is repeatable and the relevant WSLg version supports the setting.

Do not edit the read-only WSLg system distribution, copy random Weston’s environment variables from an old forum post, or restart all distros before saving evidence. Some configuration paths differ between inbox and Store-serviced WSL. Verify the exact location and current documentation for the installed channel. Remove temporary logging after capture because detailed logs can be large and may include application context.

A broad wsl –shutdown also stops all WSL 2 distributions and the shared utility VM. If restarting is justified, save work, record the prior failure, then restart and repeat the same marker test. A temporary recovery after restart is useful evidence of stale state but not proof that the issue is fixed if it returns after a normal app launch.

Common failure patterns

If only terminal text selection fails, inspect Windows Terminal’s copy settings and selection behavior. If only one Linux GUI application fails, inspect that application’s display backend, sandbox, and clipboard implementation. If Wayland command-line transfer works inside Linux but not to Windows, compare WSLg version and collect clipboard logs. If Windows-to-Linux works but Linux-to-Windows does not, preserve that directional asymmetry; it can identify whether the failure is in publishing or consuming a selection.

If a Linux app works when launched from a shell but not from Start Menu, compare environment and application packaging. If native Wayland works but X11 does not, investigate XWayland and X11 selection behavior rather than replacing the whole WSLg stack. If behavior changes after an update, record Windows build, WSL version, distro, application version, and protocol path before reproducing.

Treat payload size and ownership as part of the test

Clipboard APIs often transfer data on demand rather than copying a file into a shared directory. A tiny text marker can prove protocol reachability but does not validate large selections, rich formats, images, or application-specific MIME offers. If a workflow depends on those, test each required content type with a non-sensitive sample and include a size bound. Do not move confidential clipboard material through a generic diagnostic tool just to test transport.

Clipboard ownership can also change when another application publishes a new selection. If a copied value disappears, record which application most recently wrote to the clipboard and whether the test uses X11 PRIMARY or CLIPBOARD. Test a single writer and reader first, then introduce the full application pair. This avoids mistaking normal selection replacement for a WSLg synchronization defect and keeps the diagnostic payload narrowly scoped.

Acceptance criteria for a supported workflow

Define the application, version, display protocol, source, destination, direction, and selection being tested. Verify a short harmless marker from Linux GUI to Windows and Windows to Linux. If both terminal and GUI copy/paste are required, test them as separate workflows. Repeat after a fresh WSLg application launch and after a full VM restart only when lifecycle reliability is in scope.

A useful bug report says exactly which direction and application pair failed, whether the Linux-side clipboard utility round-tripped, the values of the display variables, and whether a terminal selection behaved differently. Avoid sharing clipboard contents from production: clips can contain credentials or personal information. The marker is sufficient to establish transport.

Related:

Sources: