Poor documentation and confusing use cases can make it hard to learn about environment variables. If you hack on Wayland (whether as a shell developer, application developer or just curios user), these might be useful. Running programs natively under Wayland from the Sway team may also be of interest.
$WAYLAND_DISPLAY
This tells Wayland clients which Wayland compositor to connect to. If it is not set, clients will try wayland-0 as a fallback. WAYLAND_DISPLAY is normally the name of a socket in XDG_RUNTIME_DIR, but it can also be an absolute path to a socket anywhere.
Compositors generally also respect WAYLAND_DISPLAY if set. Some will use wayland-0 by default, and others wayland-1. If its default display is already taken, a compositor will either count up until they find a free one or fail to start. Note that the wayland-[0-9] pattern is common, but compositors can create their display with whatever name they like.
If you want to make absolutely sure an app isn’t running on Wayland, launch it with WAYLAND_DISPLAY set to something that definitly doesn’t exist. I use WAYLAND_DISPLAY=no for this.
$XDG_RUNTIME_DIR
The directory where the Wayland display socket is created. Generally set to /run/user/1000. You can see what displays are currently open by running ls $XDG_RUNTIME_DIR/wayland-* (assuming compositors are using the wayland- prefix). lsof $XDG_RUNTIME_DIR/wayland-* will give you additional information, including showing which compositor is running on which display.
$WAYLAND_DEBUG
This causes libwayland to dump protocol messages to stderr. If it’s set to 1, all messages are dumped. If instead it’s set to client or server, only messages coming from that type of connection are shown.
For normal apps server will show nothing and client will show all output. Servers can, however, use both the client and server library, and for that the filtering is useful. For example, a server may run as a client inside another Wayland compositor or it may connect to itself to provide a desktop background. In both cases it opens client connections you might want to filter out.
This variable is useful for checking if a client is using Wayland, but reading the output raw is not an enjoyable experience. If you’re trying to actually understand what’s going on, I suggest using my wayland-debug tool.
$DISPLAY
The environment variable used by X11 clients to select an X display. Generally set to :0, :1, etc. The X display sockets are located in /tmp/.X11-unix/. Unlike Wayland clients, X clients do not try a fallback display if the variable is unset.
Most Wayland compositors support XWayland, which looks identical to a normal X11 server from apps’ perspective.
$GDK_BACKEND
NOTE: it’s GDK_BACKEND, not GTK_BACKEND (GDK is the subsystem of GTK that handles windowing).
Controls how GTK apps run. Can be a single backend or a comma separated list of backends, in which case they will be tried in the given order. The backends relevant to Linux are x11 and wayland (so, x11,wayland means first try X/XWayland, then try Wayland). Apps also have a say in what backends they work on and default to. I could write a whole other post about the quarks of GTK backend selection, and I did.
$QT_QPA_PLATFORM
This controls how Qt apps run. It can be set to xcb for X11 or wayland-egl for Wayland.
$XDG_SESSION_TYPE
This effects Qt (if QT_QPA_PLATFORM is unset) and other non-GTK toolkits. Can be x11 or wayland.
$MOZ_ENABLE_WAYLAND
Enables Wayland for Mozilla products (notably Firefox) if set to 1. Firefox uses GTK so setting GTK_BACKEND=wayland will force it to run on Wayland regardless of if MOZ_ENABLE_WAYLAND. However, it will default to X on GDK_BACKEND=wayland,x11 unless MOZ_ENABLE_WAYLAND=1 is set.
$_JAVA_AWT_WM_NONREPARENTING
Many Java apps (such as Intellij) don’t support Wayland natively and break on most XWayland implementations (and other non-reparenting window managers). This often results in blank screens. To make them work, set _JAVA_AWT_WM_NONREPARENTING=1. I consider this a toolkit bug, but it seems unlikely to be fixed.
Feel free to leave any I missed in the comments below, as well as any tips and tricks you may have picked up.
