I have been a fan of tiling window manager for many years now. I’ve used Awesome WM, bspwm, and i3 at various points in time. However, it wasn’t until recently that a wayland-based TWM became mature enough for me to consider using. This article is intended to document how I got my setup working. It is not intended to teach you TWM basics, although it is pretty easy to learn. Since Sway aims to be largely a drop-in replacement for i3, most of the i3 documentation and usage applies. By extension, looking up “i3 wm tutorial” on the internet will get you some useful info if you’re new to things.

The basics

When I first started using Sway, I did so in Ubuntu 20.04. This worked fine, however some of the base Ubuntu install occasionally showed through or caused minor weirdness. The old kernel and package versions certainly didn’t help either. You also have the weight of whatever your original install was, which you don’t need if sway is your primary WM.

Due to these factors I would advise anyone considering running Sway to use a rolling release distro like Arch or Gentoo. This is all basic stuff though, so let’s get on to the interesting bits.

Seeing as sway is intended to replicate the i3 window manager to some degree, it is useful to look through the docs for configuring that since most things will apply. Read through the initial config and manpages as well, they contain good examples.

Hardware setup

I have an obnoxious number of peripherals. Even in xorg it’s a pain to get things configured right. As a quick note, I am using an AMD GPU (Vega 64), and I have heard Nvidia support is less than stellar in wayland as of right now.

Displays

I have 2 1440p displays in a stacked orientation. The kicker is that the bottom one is a 144hz VRR monitor, and the top is a 60hz fixed monitor. The newest version of sway as of this writing has support for setting VRR.

The easiest way to do VRR is to just slap output * adaptive_sync on somewhere in your sway config. This will turn on VRR on any displays that support it and I’ve found that it pretty much “just works” with both windowed and fullscreen programs, something that not even windows supports as far as I am aware. Games seem to adapt automatically if you turn vsync off in their settings.

For layout, you can manually position your displays in the sway config file, or use wdisplays for a nice GUI monitor layout interface.

Input devices

I have the regular mouse and keyboard like most people, which I don’t do any special configuration for. I also have a graphics tablet, specifically a Huion WH1409. By default, the drawing area is mapped across both monitors which is not great. Fortunately, Sway supports mapping tablets and touchscreens. For my specific tablet, I was able to just use

input 9580:110:TABLET_Pen_Tablet_Pen map_to_output DP-1

to map my tablet to my primary display.

Besides those things, I also have a MIDI keyboard, which is not handled by wayland in the first place. I also have an Xbox One controller which works as expected through bluetooth via xpadneo. Steam controllers also largely work with no hitches.

Audio

Wayland doesn’t have anything to do with audio but I figured I’d go ahead and mention pipewire. Whether in xorg or wayland, pulse is an eternal thorn in my side and pipewire has arleady proven itself to be considerably more sane despite its early stage in development. Explore this on your own.

Visuals

I did my fair share of linux ricing in high school. These days I just get some sane themes and colorschemes and get on with my life. Colorschemes work like i3, go read the docs for that.

To get themes working is a bit trickier. We need to theme both Qt and GTK. The easiest place to start is gtk. The same themes work, but applying them is not quite as easy as a traditional DE or some other WMs.

In my sway config, I have an autostart section like so:

exec_always {
    gsettings set $gnome-schema gtk-theme 'Arc-Dark'
    gsettings set $gnome-schema icon-theme 'Arc'
    gsettings set $gnome-schema cursor-theme 'Adwaita'
    ...
}

On arch linux, this will set the gtk, icon, and cursor theme. I picked Arc but you can use anything.

For Qt, there’s a few options. To start, I got qt5ct and added export QT_QPA_PLATFORMTHEME=qt5ct to my ~/.profile. This lets us easily configure our Qt settings with qt5ct.

For the theme, you can have Qt just use the GTK theme, but I prefer to go native. In my setup, I use Kvantum as my Qt theme which has it’s own configuration tool and a wide selection of styles. Conveniently, it has an Arc-Dark preset shipped with it, which matches the GTK theme without the overhead of GTK.

Terminal

You have a lot of flexibility here, but the best modern terminals in my opinion are Kitty and Alacritty. Both of them support native Wayland, and fun features like color schemes, proper font rendering, and transparency, all of which should work without any additional effort beyond their respective configurations.

Wallpapers

I like having my wallpapers rotate out so I see something fresh. Unfortunately, there is no out of the box solution for rotating wallpapers (yet). You can set them manually in your sway config but they won’t change. I initially wrote a script that used sway output to change the wallpaper every hour, but I found that this had multiple issues, namely that it would run multiple instances of the script if I reloaded the config, and it would cause a multiple-second system freeze whenever the wallpapers changed.

After some small amount of work I reworked the script to have a lock file so it doesn’t run multiple times, and to use swaybg directly, as described in this article.

I uploaded my script here, to use add it to the exec_always block from earlier.

Web browsing

Firefox is my browser of choice. However, it does require a few tweaks to work its best in sway. First off, you need to run it with the environment variable MOZ_ENABLE_WAYLAND=1. You can add a line to your .profile that reads export MOZ_ENABLE_WAYLAND=1.

You should also enable webrender and set your refresh rate in about:config. FF did not automatically pick up my 144hz display and I had to set it manually. FF may also be getting webrender toggled on by default in newer versions in linux. In any case this provides a butter smooth browsing experience except for desktop notifications that get handled like a regular window, which brings us to…

Notifications

Sway doesn’t have a notification server built in, so applications will just create their own notifications even if they have dbus support. Many apps do not play so well with this, so it is advisable to use a notification server with first class wayland support. The one I settled on is mako. Other than color scheme, the only thing I changed was default-timeout to be 7000ms, as by default the notifications will never go away unless the application specifies a timeout.

To run it, I simply added mako inside my exec_always section.

Launcher

If you’ve never used a tiling wm before, they often require you to bring your own application launcher as opposed to providing one for you (a notable exception being Awesome WM). In the past I’ve used both dmenu and rofi. Both of these will work but xwayland will cause input handling and monitor usage to be a bit weird. Because of this, much like notifications, it is best to find a launcher that has native wayland support. I landed on wofi which is a near drop-in for rofi with only a couple missing features.

Games

Games usually just work. The only catch is that the game window has to be focused to receive input, even with a controller. This is by design and currently cannot be worked around.

Sometimes games won’t work as expected. The windows will disappear or become unfocusable, or it won’t go fullscreen properly, detect the displays, etc. This is when I like to bust out one of my new favorite tools, gamescope. This little program basically sets up a nested wayland compositor that emulates an output to your specifications. This output is the only display the program sees, and as far as it’s concerned, it’s fullscreen and in focus at all times.

I usually just use it by running gamescope -w 2560 -h 1440 -- COMMAND_HERE. In steam, you can set that in launch options by replacing COMMAND_HERE with %command%.

I have found that this fixes the vast majority of funkieness involving window management and input shenanigans.

VR

VR doesn’t work in wayland yet at all. I keep around an LXQt desktop and switch to that when I want to use my Valve Index. There was some work implementing the features required, mostly DRM leasing, but it seems these efforts are stalled out at the moment.