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.
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.
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
lsof $XDG_RUNTIME_DIR/wayland-* will give you additional information, including showing which compositor is running on which display.
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
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.
The environment variable used by X11 clients to select an X display. Generally set to
: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.
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,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.
This controls how Qt apps run. It can be set to
xcb for X11 or
wayland-egl for Wayland.
This effects Qt (if
QT_QPA_PLATFORM is unset) and other non-GTK toolkits. Can be
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
MOZ_ENABLE_WAYLAND=1 is set.
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.