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 : : 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!



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.


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:

(Video) System Crafters Live! - Can We Fix a Bug in Emacs?

  • 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


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.


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


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!


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:

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

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


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

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

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):


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:

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


Converting from Chromium is a bit easier. in the/home/you/.config/chromium-flags.conf, add the following lines:


Restart Chromium and that should be it. You can confirm withxlsclients.


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:

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

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.


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.


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:


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:

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

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:

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

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.


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.


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


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


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


How to install Wayland on Arch Linux? ›

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!

How do I enable Wayland in the arch? ›

To enable Wayland support in Qt 5 or 6, install the qt5-wayland or qt6-wayland package, respectively. On some compositors, for example sway, Qt applications running natively might have missing functionality. For example, KeepassXC will be unable to minimize to tray.

Do all window managers and desktop environments work with Wayland? ›

A Wayland compositor combines the roles of the X window manager, compositing manager and display server. Most major desktops support Wayland well, but for testing purposes, weston is the reference implementation of the concept.

Is Wayland better than X11? ›

One of the main reasons for X's complexity is that, over the years, its role has changed. As a result, today, X11 acts largely as “a really terrible” communications protocol between the client and the window manager. Wayland is also superior when it comes to security.

Does Wayland use more RAM? ›

For example Wayland uses more RAM as full backing buffers for every window, and this actually makes moving windows around faster because it doesn't have to ask the app to re-draw exposed areas.

Can Wayland run X11 apps? ›

Architecture. An X11 application connects to Xwayland just like it would connect to any X server. Xwayland processes all the X11 requests.

Does VLC work on Wayland? ›

vlc-gitAUR builds with Wayland support by default. Set the QT_QPA_PLATFORM=wayland environment variable to enable Wayland.

How do I know if Wayland is enabled? ›

Wayland is enabled by default in the GNOME Desktop. You can choose to run GNOME in X11 by choosing the Gnome on xorg option in the session chooser on the login screen.

How do I change my X11 to Wayland? ›

On the password screen, you will find a cogwheel icon at the bottom-right corner. Click on the cog and select “Ubuntu” or “Ubuntu on Xorg” to switch to Xorg. And if you want to use Wayland, select “Ubuntu on Wayland”.

How do I set Wayland as my default? ›

Changing the default GNOME session via configuration file
  1. Open /etc/gdm/custom.conf and uncomment the line: WaylandEnable=false.
  2. Add the following line to the [daemon] section: DefaultSession=gnome-xorg.desktop.
  3. Save the custom. conf file.
  4. Logout or reboot to enter the new session.

Can NVIDIA use Wayland? ›

The nvidia GPU by default (especially with wayland) only controls the external monitor while the IGP controls the internal screen. If you want the nvidia card to function all the time, or even to have control of the internal screen it may be necessary to follow the steps here, including the copy of the nvidia.

Can you play games on Wayland? ›

Wine-wayland allows playing DX9/DX11 and Vulkan games using pure wayland and Wine/DXVK.

Is Wayland usable with NVIDIA? ›

NVIDIA binary Linux drivers do support Wayland.

How do I know if I have Wayland Arch or X11? ›

Check whether Wayland or Xorg is in use

If you use xorg (X display server), you should get x11 in the output. To summarize: Check the value of $XDG_SESSION_TYPE variable in terminal. For Wayland, you get wayland and for Xorg you get in the output.

Does GNOME run on Wayland? ›

GNOME, the default, runs GNOME Shell on Wayland. Traditional X applications are run through Xwayland. GNOME Classic provides a "traditional desktop experience" (with an interface similar to GNOME 2) by using certain extensions and values.

How do I enable Wayland NVIDIA? ›

Nvidia (prop) driver support in wayland session
  1. Enable Wayland support on the Nvidia kernel driver by adding this to your command line: nvidia-drm.modeset=1. which is done in /etc/default/grub .
  2. Run: sudo update-grub.
  3. Verify in /etc/gdm3/custom. conf that you don't still have Wayland disabled.
  4. Reboot.

How do I change from X11 to Wayland Arch? ›

First, you need to enable NVIDIA kernel modesetting, to do this add the kernel parameter nvidia-drm. modeset=1. Next, ensure that GDM wayland isn't disabled (this isn't strictly necessary since you can launch GNOME from command line). Go to /etc/gdm/custom.

How do I switch from X11 to Wayland? ›

On the password screen, you will find a cogwheel icon at the bottom-right corner. Click on the cog and select “Ubuntu” or “Ubuntu on Xorg” to switch to Xorg. And if you want to use Wayland, select “Ubuntu on Wayland”.

How do I activate GNOME Wayland? ›

Changing the default GNOME session via configuration file
  1. Open /etc/gdm/custom.conf and uncomment the line: WaylandEnable=false.
  2. Add the following line to the [daemon] section: DefaultSession=gnome-xorg.desktop.
  3. Save the custom. conf file.
  4. Logout or reboot to enter the new session.

How do I know if Wayland or X11 is running? ›

Determining whether you are using Wayland

If the window is running in wayland it will say “MetaWindowWayland” and if it is running in X11 it will say “MetaWindowX11”.

How do I know if I'm using Wayland? ›

Check whether Wayland or Xorg is in use
  1. Check the value of $XDG_SESSION_TYPE variable in terminal.
  2. For Wayland, you get wayland and for Xorg you get in the output.
Sep 15, 2022

Do X11 apps work on Wayland? ›

An X11 application connects to Xwayland just like it would connect to any X server. Xwayland processes all the X11 requests. On the other end, Xwayland is a Wayland client that connects to the Wayland compositor.

What is the point of Wayland? ›

Wayland is a communication protocol that specifies the communication between a display server and its clients, as well as a C library implementation of that protocol. A display server using the Wayland protocol is called a Wayland compositor, because it additionally performs the task of a compositing window manager.

Why should I switch to Wayland? ›

The first and most obvious reason why you would want to use Wayland instead of X11 is the reduced latency between opening an application and having it render on your desktop. It also makes tasks such as dragging windows, resizing them or switching them to full screen feel that much more smooth and modern.

Is Pop OS running on Wayland? ›

Pop!_ OS currently uses Xorg as its display manager, with Wayland available optionally. TensorFlow and CUDA enabled programs can be added by installing packages from the Pop!_ OS repositories without additional configuration required.

How do I enable Wayland Nvidia? ›

Nvidia (prop) driver support in wayland session
  1. Enable Wayland support on the Nvidia kernel driver by adding this to your command line: nvidia-drm.modeset=1. which is done in /etc/default/grub .
  2. Run: sudo update-grub.
  3. Verify in /etc/gdm3/custom. conf that you don't still have Wayland disabled.
  4. Reboot.

Does Wayland use Vulkan? ›

Most Wayland compositors will use both GBM and OpenGL via Mesa, and most Wayland clients will use at least its OpenGL or Vulkan implementations.

Does Arch Linux have a GUI? ›

Arch Linux GUI isn't a distribution. It simply provides an easy-to-use installer for Arch Linux. Their website offers versions featuring GNOME, KDE Plasma, XFCE, Cinnamon, and the i3 window manager. Apart from i3, these are offered in “pure” or “themed” variants.

Top Articles
Latest Posts
Article information

Author: Arielle Torp

Last Updated: 02/25/2023

Views: 6776

Rating: 4 / 5 (61 voted)

Reviews: 92% of readers found this page helpful

Author information

Name: Arielle Torp

Birthday: 1997-09-20

Address: 87313 Erdman Vista, North Dustinborough, WA 37563

Phone: +97216742823598

Job: Central Technology Officer

Hobby: Taekwondo, Macrame, Foreign language learning, Kite flying, Cooking, Skiing, Computer programming

Introduction: My name is Arielle Torp, I am a comfortable, kind, zealous, lovely, jolly, colorful, adventurous person who loves writing and wants to share my knowledge and understanding with you.