Colin Woodbury - Complete Wayland setup on Arch Linux (2023)

This article is a guide to achieving the most complete possibleWaylandSetup on Arch Linux. If you follow the entire guide you will end up with:

• Vary, a tile window manager.
• signpost, a topbar that is very similarPolybar.
• Wofi, a pure GTK (and thus Wayland) customizable application launcher.
• speed, a modern terminal that "just works".
• Firefox and/or Chromium in Wayland with working screen sharing.
• Emacs runs entirely in Wayland over brand new pure GTK internals.
• MostQT applications running in Wayland.
• Steam games have been set up to consider Wayland when they can.
• (Optional) Japanese input viaFcitx5.

You will also learn how to confirm whether or not an app is running in Wayland and become aware of itXWaylandand important programs that still need it to run properly. Although this guide was written with Arch Linux in mind, it should be adaptable to whatever brand of Linux you run. Enjoy and good luck!

Note:You may want to open this guide on a phone or a second computer before proceeding as we will need to restart your window manager several times.

Foreword: Wayland? XWayland?

Wayland is the next generation display protocol for Linux. You've probably heard of "X" (or "X11" or "XOrg"), but you might not have known about its problems: age, performance, security, and developer-friendliness. Even Adam Jackson, X's longtime release managercalls for Wayland to be adopted. However, X is well established and the transition will not happen overnight. Many core apps on a Linux system are tightly tied to its ecosystem:

> pacman -Qg xorg | wc-l38

But you might be surprised to learn that you almost certainly haveRoadlandalready installed.

> pacman -Qi waylandName : waylandVersion : 1.19.0-1Description : A computer display server protocolArchitecture : x86_64URL : https://wayland.freedesktop.org/Licenses : MIT# ... etc.

Luckily for us, the Linux ecosystem transitioned to Waylandmarch steadily forwardover the years. The main GUI frameworks like GTK and QT fully support it.Ubuntu 21.04 runs with Wayland by default. But you don't have to wait for big distros to move: we can jump to Wayland today.

You should know that there are some important applications that don't (or won't) do this.or can not) support Wayland. Programs like this can still be run in a Wayland environment via an isolated X instance being invokedXWayland. This means that the transition to Wayland can be done gradually: you don't lose access to older programs that you still need.

One last piece of good news before we continue: in Wayland you don't need a compositor program likePicomorcompizthis is separate from your window manager. Translation? Fewer moving parts, less configuration to manage, and terminal transparency just works!

requirements

PACKAGES

On Arch Linux, run the following command to install everything you 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-waylandandglfw-waylandprovide Wayland API compatibility for QT5 andGLFWrespectively.xlsclientsis explained below.

Detection of XWayland withxlsclients

To get a list of all windows currently running through XWayland, usexlsclients:

> xlsclientsarchlinux discordarchlinux steam

This allows you to quickly test your Wayland configuration with different applications.

Vary

Sway is a tile window manager and drop-in replacement fori3. Like its inspiration, it is written in C and is therefore very fast and has a low resource footprint. Although Sway can read the i3 configuration as is (i.e. your/home/you/.config/i3/config), I recommend starting with a blank slate and then copying specific bindings as needed.

First, copy Sway's configuration template:

cd ~/.configmkdir swaycd swaycp /etc/sway/config .

Now exit the desktop environment/window manager you are in and switch to your basic login terminal. Walk from herevaryand Sway should start. Congratulations, you're running Wayland!

Well, let's not celebrate too soon. You may be used to having lines likeexeci3in one.xinitrc, then starting with Xstartx. No longer! From here everything happens in our Sway configuration. Speaking of which, here are some highlights below.

Sway configuration and extras

Here is my complete Sway configuration. Otherwise, Sway is mostly documented in its man pages. If in doubt, check these first. If that fails, you can also consult theSway-Wiki.

Here are some useful bindings that you need right now but can change later:

• Reload Sway:Super+Shift+c(does not close your running programs)
• Quit Sway:Super+Shift+e
• Open a terminal:Super+Return
• Open a program:Super+d

Monitor-Setup

I have two monitors: my laptop on my left and my real monitor directly in front of me. In order for my mouse to naturally move over the monitor boundary, it requires the following:

Output eDP-1 mode 2560x1440 position 0.0 scaling 2Output HDMI-A-2 mode 1920x1080 position 1280.0

Some math is required to determine the correct offset for the second monitor (the1280in the second line). Seeman sway-outputfor more informations. You can useswaymsg -t get_outputsto see the official names and available resolutions of all your monitors.

Gaps

i3 gapsis a popular i3 variant that allows gaps between windows. Luckily, this functionality is already built into Sway and can be enabled by adding the following anywhere in your Sway configuration:

# A 10px border around each window. gaps inner 10 # Removes the title bar of each window. default_border pixels 3

you will needexitWaver once and run it again from your login terminal for the change to take effect.

Random wallpapers

setwallcan be used to set a random wallpaper every time to launch Sway:

exec_always setwall random ~/Pictures/backgrounds/ -c sway

speed

Alacritty is a great modern terminal emulator with reasonable default settings. It's also the default for Sway when opening a new terminal withSuper+Return. I useurxvtfor years, but when I recently switched to Alacritty, a number of issues I had just went away.

The only thing I change from Alacritty's default configuration is the background opacity. Inside/home/you/.config/alacritty/alacritty.yml:

window: opacity: 0,8

Voila, transparente Terminals!

signpost

The default bar for Sway is pretty good, but Waybar offers a lot more customizability. It also "works" on multiple monitors, unlike Polybar which requires custom scripting.

To use Waybar instead of the default bar, comment that outBarsection at the end of your Sway configuration and add the following instead:

bar { swaybar_command waybar }

The Waybar Wikihas many example configurations andhere is my ownalong withits custom CSS styling. The bar itself is transparent, with the widgets and tray at the top right looking like this:

After customizing your Waybar configuration, it is enough to update Sway viaSuper+Shift+cas usual to update your waybars as well.

Wofi

By default it uses Swaydmenuto open programs, but surprisingly its user interface runs in XWayland. There isa number of alternativesavailable and I choseWofi.

this is thatLook, I've made my decision, but since it's all CSS, you areexperiment freely! Note that you need the following in your Sway configuration:

set $menu wofi --show=drun --lines=5 --prompt=""

There are a few different prompt modes.thereonmatches matches only and displays matches for programs that have "desktop" entries anywhere on your computer, as opposed to anything on your PATH. Failure to do this can and does actually cause performance issuesa known issue.

Important Applications

Most applications running on GTK or QT have automatic Wayland support and require no further configuration. Some specific programs require tweaks, which we'll detail below.

A number of recent resources claim that you need GTK and QT specific environment variables in order to use Wayland, butI didn't think that was true.

fire fox

ThatAbout: supportPage in Firefox has a field titledWindows-Protokollthat tells us what protocol it's going through. If you are still on X11, this field saysx11. If you go through Sway without the tweak below, you should seeDream. quick test withxlsclientsshould also show that Firefox doesn't run natively through Wayland yet. Let's fix that.

Set thoseMOZ_ENABLE_WAYLANDenvironment variable too1. I place the following in my fish configuration (users of other shells need something similar):

set -x MOZ_ENABLE_WAYLAND 1

Quit Sway and log out completely once.After logging back in and reopening Sway, this variable change should have propagated to all relevant places. Now if you open Firefox again through Wofi and checkAbout: support, you should find:

Chrom

Converting from Chromium is a bit easier. in the/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 withxlsclients.

Emacs

Yes, Emacs can be run purely in Wayland. Some of you might say:

But Emacs is not a true GTK app!

And yes, that was right.As of early 2021, Emacs can be built with "pure GTK" internals, making it fully Wayland compatible. This feature will be available in Emacs 28 (still unreleased at the time of this writing), but thankfullyThere is an AUR packagewhich follows the Wayland development branch and ships a prebuilt binary. We can install it with a tool likeAura:

sudo aura -Axa emacs-gcc-wayland-devel-bin

Note that this packageProvides: emacs, so it replaces any other Emacs package you have installed.

When you're ready to create the master branch and thereby gain early access to Emacs 29, you can set the background opacity of Emacs with:

(set-frame-parameter nil 'alpha-background 80)

achieve native transparency.

steam and games

proton gamesLikesBetween uswork as is as they run in a highly optimized wine/dependency environment that is known to work for every game.Between usResponds well to resizing and moving windows within Sway.

In order for native games like Half-life (old), Trine 2 (graphics heavy) and Tabletop Simulator (modern toolchain) to work, I had to set the environment variableSDL_VIDEODRIVERtox11. Otherwise they will not start properly. From the Arch wiki:

Note: Many proprietary games ship with old versions of SDL that don't support Wayland and may break completely if you set SDL_VIDEODRIVER=wayland.

Also Stellaris requiresx11work.

If you don't want to force all SDL usage to X11, you don't have to. Steam allows us to set certain per-game environment variables. To set this, right click on a game and visit itCharacteristics. ImGENERAL > STARTUP OPTIONS, type the following and your game should be up and running:

To reiterate, here is the environment variable I set in Fish:

set -x SDL_VIDEODRIVER 'Wayland'

And I override thisx11on a case by case basis within Steam.

Signal

In early May 2021, Signal was released5.1.0which uses a Wayland-compatible version of Electron. Unfortunately the Arch packageSignal-DesktopDoes not run in this mode by default, so manual activation is required. From the command line:

Signal-Desktop --use-tray-icon --enable-features=Use the OzonePlatform--ozone platform=Roadland

Or if you're running Signal from a launcher, we can edit that.DesktopFile provided by the package to include these options as well. Inside/usr/share/applications/signal-desktop.desktop, change theversionline to have:

Exec=signal-desktop --use-tray-icon --enable-features=UseOzonePlatform --ozone-platform=wayland -- %u

A similar strategy would work for other Electron apps using at least version 12.

Other options

If the sections here don't apply to you, feel free to skip them.

Tastaturlayouts

I'm using the Colemak layout when typing, so I have the following in my Sway configuration:

input * { xkb_layout "us" xkb_variant "colemak" }

Unfortunately, there seems to bea strange mistakewhere the layout in certain windows suddenly switches back to qwerty. I've noticed the following symptom: when a terminal is opened, the leftmost XWayland window switches back to qwerty. I found two ways to work around this:

• Use as many Wayland-only apps as possible, or;
• Install an IME (Input Method Editor), for example for typing in non-ASCII languages ​​(see below).

Japanese entrance

Sway comes very close to first class support for input method switching (seeWaver#4740,Waver#5890, andWaver#4932). For now here is a setup that works over dbus and allows us to change methods and type Japanese in all Wayland and XWayland windowsexcept Alacritty.

Install these packages first:

sudo pacman -S fcitx5 fcitx5-configtool \ fcitx5-gtk fcitx5-mozc fcitx5-qt

Then add the following/etc/environment:

GTK_IM_MODULE=fcitx QT_IM_MODULE=fcitx XMODIFIERS=@im=fcitx

And this for your Sway configuration:

exec_always fcitx5 -d --replace

Now restart your computer.

Hopefully you will now see a keyboard icon in your waybar. Configurefcitx5, openfcitx5-configtool. Here is my setup:

You will see that I specially set and added my English keyboard to ColemakBrainfrom the list on the right. Check theGlobal optionsTab to define the button assignment for the method change. Then strikeApply, and you should now be able to switch input methods and type in Japanese. If the keybinding doesn't work, you can also switch methods by clicking the icon in the waybar bar.

split screen

Screen sharing in Firefox and Chromium is possible via Pipewire and some helper packages, although at the moment we can only share entire screens and not individual windows. First install the following packages to continue:

sudo pacman -S xdg-desktop-portal-wlr libpipewire02

The latter is only necessary for Chromium.Now restart your computer.

Let's test Firefox with Mozilla firstGum Test Page. When the browser prompts you to choose a window, chooseUse operating system settings:

You'll notice your cursor change;xdg-desktop-portal-wlrexpects you to select a display to share. Click one and screen sharing should begin.

For Chromium, we need to enable a feature flag to allow Chromium to communicate with Pipewire. First visitchrome://flags, then find and activate theWebRTCPipeWire supportspecial feature. That's it!

If you're having trouble with any of these browsers, check them outXDPW-FAQ.

XWayland and incompatibilities

Do you know of other incompatibilities?Please let me know.

Elektron-Apps

As of May 2021, Signal and VSCode can now run in Wayland thanks to their upgrade to Electron 12.

Other Electron apps like Discord and Slack instead need to run in XWayland until they can be updated.

Community-Tipps

KWin user

Thanks toflying sheepfor this tip:

For people using KWin: You can display a window to help you identify XWayland windows by using:

qdbus org.kde.KWin /KWin org.kde.KWin.showDebugConsole

Polkit

Thanks to Aaron Wiedemer for the following suggestion:

Some apps sometimes require privileges, e.g. A software manager needs permissions to start an update, but only searching for packages does not require additional permissions. These apps will then open a small box and ask for the password. This requires a daemon that isn't started by Sway, so we need to auto-start one with our Sway configuration.

There are a number of options for Polkit clients.For example,Polkit-Gnomhas no dependencies and can be startedvaryabove:

exec_always /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1

resources

If you found this article helpful, please consider itbuy me a coffee.

• Sway: Running GUI programs under Wayland
• Sway: i3-Migrationsleitfaden
• Waver: Waybar
• Sway: Wofi-Launcher
• Arch-Wiki: Wayland
• Are we Wayland yet?
• Blog: Zoom Screen Sharing