Full Wayland Setup on Arch Linux
This article is a guide for achieving a full-as-possible Wayland setup on Arch Linux. If you follow the entire guide, by the end you will have:
- Sway, a tiling window manager.
- Waybar, a topbar very similar to Polybar.
- Wofi, a pure GTK (and thus Wayland) customizable application launcher.
- Alacritty, a modern terminal that "just works".
- Firefox and/or Chromium in Wayland with working screen sharing.
- Emacs running fully in Wayland via brand-new pure GTK internals.
- Most QT applications running in Wayland.
- Steam games set up to consider Wayland, if they can.
- (Optional) Japanese input via Fcitx5.
You will also learn how to confirm if an app is running in Wayland or not, and will become aware of XWayland and major programs that still need it to run properly. While this guide was written with Arch Linux in mind, it should be adaptable to any brand of Linux that you run. Enjoy, and good luck!
Note: You may wish to open this guide on a phone or second computer before continuing, as we will need to restart your window manager several times throughout.
Foreword: Wayland? XWayland?
Wayland is the next generation Display Protocol for Linux. You've probably heard of "X" (or "X11" or "XOrg"), but you may not have known of its issues: age, performance, security, and dev-friendliness. Even Adam Jackson, the long-time release manager of X calls for the adoption of Wayland. That said, X is well-established and the transition won't happen over night. Many core apps on a Linux system are bound tightly to its ecosystem:
> pacman -Qg xorg | wc -l 38
But you might be surprised to learn that you almost certainly have wayland installed already.
> pacman -Qi wayland Name : wayland Version : 1.19.0-1 Description : A computer display server protocol Architecture : x86_64 URL : https://wayland.freedesktop.org/ Licenses : MIT # ... etc.
Fortunately for us, the Linux ecosystem's transition to Wayland has been marching steadily forward through the years. The major GUI frameworks like GTK and QT fully support it. Ubuntu 21.04 will run with Wayland by default. But no need to wait for major distros to move: we can jump to Wayland today.
You should know that there are some major applications that don't (or won't or can't) support Wayland. Programs like this can still be run in a Wayland environment through an isolated X instance called XWayland. This means that the transition to Wayland can be gradual: you won't lose access to older programs that you still need.
One last piece of good news before we move on: in Wayland, you don't need a compositor program like picom or compiz that's separate from your window manager. Translation? Fewer moving parts, less configuration to manage, and terminal transparency just works!
Prerequisites
Packages
On Arch Linux, run the following command to install everything you'll need for the main section of the guide and general Wayland compatibility:
sudo pacman -S \ sway alacritty waybar wofi \ xorg-xwayland xorg-xlsclients qt5-wayland glfw-wayland
qt5-wayland and glfw-wayland provide Wayland API compatibility for QT5 and GLFW respectively. xlsclients is explained below.
Detecting XWayland with xlsclients
To get a list of all windows currently running through XWayland, use xlsclients:
> xlsclients archlinux discord archlinux steam
This way, you can quickly test your Wayland config with various applications.
Sway
Sway is a tiling window manager and a drop-in replacement for i3. Like its inspiration it too is written in C, and thus is very fast and has little resource overhead. Although Sway can read i3 config as-is (i.e. your /home/you/.config/i3/config), I recommend starting with a blank slate and then copying over specific bindings as you need them.
First, copy Sway's config template:
cd ~/.config mkdir sway cd sway cp /etc/sway/config .
Now exit whatever desktop environment / window manager you're in, and drop down to your basic login terminal. From here, run sway and Sway should start. Congratulations, you're running Wayland!
Well let's not celebrate too early. You might be used to having lines like exec
i3 in a .xinitrc, then starting X with startx. No longer! From here, everything happens in our Sway config. Speaking of which, here are some highlights below.
Sway Config and Extras
Here is my full Sway configuration. Otherwise, Sway is primarily documented in its man pages. When in doubt, check them first. If that fails, you can also consult the Sway Wiki.
Here are some useful bindings that you'll need right away, but are free to change later:
- Reload Sway:
Super+Shift+c(won't close your running programs) - Exit Sway:
Super+Shift+e - Open a Terminal:
Super+Return - Open a Program:
Super+d
Monitor Setup
I have two monitors: my laptop to my left, and my proper monitor directly in front of me. Getting my mouse to move naturally across the monitor boundary requires the following:
output eDP-1 mode 2560x1440 position 0,0 scale 2 output HDMI-A-2 mode 1920x1080 position 1280,0
There is some math involved in determining the proper offset to use for the second monitor (the 1280 in the second line). See man sway-output for more information. You can use swaymsg -t get_outputs to view the official names and available resolutions of all your monitors.
Gaps
i3-gaps is a popular i3 variant that allows gaps between windows. Luckily this functionality is already included in Sway, and can be activated by adding the following somewhere in your Sway config:
# A 10-pixel border around every window. gaps inner 10 # Removes the title bar of each window. default_border pixel 3
You will need to exit Sway once and rerun it from your login terminal for the change to take effect.
Random Wallpapers
setwall can be used to set a random background image every time to boot Sway:
exec_always setwall random ~/Pictures/backgrounds/ -c sway
Alacritty
Alacritty is a great modern terminal emulator with sane defaults. It is also the default for Sway when opening a new terminal with Super+Return. I used urxvt for years, but upon switching to Alacritty recently a number of issues I had had just went away.
The only thing I change about Alacritty's default config is the background opacity. Within /home/you/.config/alacritty/alacritty.yml:
Voilà, transparent terminals!
Waybar
The default bar for Sway is pretty good, but Waybar unlocks a lot more customisability. It also "just works" on multiple monitors, unlike Polybar which requires custom scripting.
To use Waybar instead of the default bar, comment out the bar section near the end of your Sway config, and in its place add this:
bar {
swaybar_command waybar
}The Waybar Wiki has plenty of example configurations, and here is my own along with its custom CSS styling. The bar itself is transparent, with the top-right widgets and tray looking like this:
After tweaking your Waybar config, its enough to refresh Sway via Super+Shift+c as usual to refresh your Waybars as well.
Wofi
By default Sway uses dmenu for opening programs, but surprisingly its UI runs in XWayland. There are a number of alternatives available, and I chose Wofi.
This is the look I settled on, but since it's all CSS you're free to experiment! Note that you'll need the following in your Sway config:
set $menu wofi --show=drun --lines=5 --prompt=""
There are a few different prompt modes. drun only matches and displays hits for programs that have "Desktop" entries somewhere on your machine, as opposed to everything on your PATH. In fact, not doing so can have performance problems and is a known issue.
Major Applications
Most applications, if running on GTK or QT, have automatic Wayland support and require no further configuration. Some specific programs need tweaks, which we'll address below.
A number of current resources claim you need GTK and QT-specific environment variables set in order for them to use Wayland, but I found this not to be true.
Firefox
The about:support page in Firefox has a field titled Window Protocol that tells us which protocol it is running through. If still on X11, this field will say x11. If through Sway without the tweak below, you should see xwayland. A quick test with xlsclients should also reveal that Firefox isn't yet running natively through Wayland. Let's fix that.
Set the MOZ_ENABLE_WAYLAND environment variable to 1. I place the following in my Fish config (users of other shells will need something similar):
set -x MOZ_ENABLE_WAYLAND 1
Exit Sway and log out entirely once. Once logged back in and with Sway reopened, this variable change should have propagated to everywhere that matters. Now if you open Firefox again through Wofi and check about:support, you should find:
Chromium
Chromium's conversion is a bit simpler. In /home/you/.config/chromium-flags.conf, add the following lines:
--enable-features=UseOzonePlatform --ozone-platform=wayland
Restart Chromium, and that should be it. You can confirm with xlsclients.
Emacs
Yes, Emacs can be ran purely in Wayland. Some of you might be saying:
But Emacs isn't a true GTK app!
And yes, that used to be true. As of early 2021, Emacs can be built with "pure GTK" internals, making it entirely Wayland compatible. This feature will be available in Emacs 28 (yet unreleased as of this writing), but luckily there is an AUR package that tracks the Wayland development branch and ships a prebuilt binary. We can install it with a tool like Aura:
sudo aura -Axa emacs-gcc-wayland-devel-bin
Note that this package Provides: emacs, so it will take the place of any other Emacs package you have installed.
If you're willing to build the master branch and thereby get early access to Emacs 29, then you can set Emacs' background opacity with:
(set-frame-parameter nil 'alpha-background 80)
to achieve native transparency.
Steam and Gaming
Proton games likes Among Us work as-is, since they run in a highly tweaked Wine/dependency environment that is known to work for each game. Among Us reacts well to window resizing and relocation within Sway.
For native games like Half-life (old), Trine 2 (graphics heavy), and Tabletop Simulator (modern toolchain) to work, I had to set the environment variable SDL_VIDEODRIVER to x11. Otherwise they fail to start properly. From the Arch Wiki:
Note: Many proprietary games come bundled with old versions of SDL, which do not support Wayland and might break entirely if you set SDL_VIDEODRIVER=wayland.
Even Stellaris requires x11 to work.
If you don't want to force all SDL usage to X11, you don't have to. Steam allows us to set specific environment variables per game. To set this, right-click on a game, and visit its Properties. In GENERAL > LAUNCH OPTIONS, enter the following and your game should be runnable:
So to reiterate, here is the environment variable I have set in Fish:
set -x SDL_VIDEODRIVER 'wayland'
And I override this to x11 on a case-by-case basis within Steam.
Signal
In early May of 2021, Signal released 5.1.0 which uses a Wayland-compatible version of Electron. Unfortunately the Arch package signal-desktop doesn't yet run in this mode by default, so manual activation is necessary. From the command line:
Or if you run Signal via a launcher, we can edit the .desktop file provided by the package to respect these options as well. Within /usr/share/applications/signal-desktop.desktop, alter the Exec line to have the following:
Exec=signal-desktop --use-tray-icon --enable-features=UseOzonePlatform --ozone-platform=wayland -- %u
A similar strategy would work for other Electron apps that use at least version 12.
Other Settings
If the sections here aren't applicable to you, feel free to skip them.
Keyboard Layouts
I use the Colemak layout when typing, so I have the following in my Sway config:
input * {
xkb_layout "us"
xkb_variant "colemak"
}Unfortunately there seems to be a strange bug where the layout will suddenly switch back to qwerty in certain windows. I noticed the following symptom: when a terminal is opened, the left-most XWayland window will switch back to qwerty. I found two ways around this:
- Use as many pure Wayland apps as possible, or;
- Install an IME (Input Method Editor), for instance for typing non-ASCII languages (see below).
Japanese Input
Sway is very close to having first-class support for switching Input Methods (see Sway#4740, Sway#5890, and Sway#4932). For now, here is a setup that works through dbus allowing us to change Methods and type Japanese in all Wayland and XWayland windows except Alacritty.
First, install these packages:
sudo pacman -S fcitx5 fcitx5-configtool \
fcitx5-gtk fcitx5-mozc fcitx5-qtThen add the following to /etc/environment:
GTK_IM_MODULE=fcitx QT_IM_MODULE=fcitx XMODIFIERS=@im=fcitx
And this to your Sway config:
exec_always fcitx5 -d --replace
Now restart your computer.
Hopefully you now see a keyboard icon in your Waybar tray. To configure fcitx5, open fcitx5-configtool. Here is my setup:
You'll see that I specifically set my English keyboard to Colemak, and added Mozc from the list on the right. Check the Global Options tab to set your Method switching keybinding. After that, hit Apply, and you should now be able to switch Input Methods and type Japanese. If the keybinding doesn't work, you can also switch Methods by clicking the icon in the Waybar tray.
Screen Sharing
Screen sharing in Firefox and Chromium is possible through Pipewire and some helper packages, although at the moment we can only share entire screens and not individual windows. To proceed, first install the following packages:
sudo pacman -S xdg-desktop-portal-wlr libpipewire02
The latter is necessary only for Chromium. Now restart your computer.
Let's test Firefox first using Mozilla's gum test page. When the browser prompts you for a window selection, choose Use operating system settings:
You will notice your cursor change; xdg-desktop-portal-wlr is expecting you to choose a display to share. Click one and screen sharing should begin.
For Chromium, we need to activate a feature flag to allow Chromium to talk to Pipewire. First visit chrome://flags, then find and enable the WebRTC
PipeWire support feature. That's it!
If you're having issues with either of these browsers, check the XDPW FAQ.
XWayland and Incompatibilities
Know of any other incompatibilities? Please let me know.
Electron Apps
As of 2021 May, Signal and VSCode can now be ran in Wayland thanks to their upgrading to Electron 12.
Other Electron apps like Discord and Slack instead must run in XWayland until they can upgrade.
Community Tips
KWin Users
Thanks to flying-sheep for this tip:
For people using KWin: You can display a window helping you to identify XWayland windows using:
qdbus org.kde.KWin /KWin org.kde.KWin.showDebugConsole
Polkit
Thanks to Aaron Wiedemer for the following suggestion:
Some apps sometimes require priveleges, e.g. a software manager needs permissions to start an update, but just searching for packages requires no additional permissions. These apps then pop up a little box and ask for the password. This requires a daemon which is not started by sway, so we need to auto start one with our sway config.
There are a number of options for Polkit clients. For instance, polkit-gnome has no dependencies and can be started in sway via:
exec_always /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1
Resources
If you found this article helpful, please consider buying me a coffee.