A Guide to Switching From i3 to Sway

[Updated June 2023: While I do still love Sway, fighting to get video and audio editors working properly in Wayland took too much time. I gave up and went back to X.org with Openbox.]

I recently made the switch from the i3 tiling window manager to Sway, a Wayland-based i3 clone. I still run Arch Linux on my personal machine, so all of this is within the context of Arch.

I made the switch for a variety of reasons. There’s the practical: Sway/Wayland gives me much better battery life on my laptop. As well as the more philosophical: Sway’s lead developer Drew Devault’s take on code is similar to mine¹ (e.g. avoid traumatic changes or avoid dependencies), and after reading his blog for a year he’s someone whose software I trust.

I know some people would think this reason ridiculous, but it’s important to me that the software I rely on be made by people I like and trust. Software is made by humans, for humans. The humans are important. And yes, it goes the other way too. I’m not going to name names, but there are some theoretically good software out there that I refuse to use because I do not like or trust the people who make it.

When I find great software made by people who seem trustworthy, I use it. So I switched to Sway and it’s been a good experience.

Sway and Wayland have been very stable in my use. I get about 20 percent more out of my laptop battery. That seems insane to me, but as someone who lives almost entirely off solar power it’s a huge win I can’t ignore.

Before You Begin

I did not blindly switch to Sway. Or rather I did and that did not go well. I switched back after a few hours and started doing some serious searching, both the search engine variety and the broader, what am I really trying to do here, variety.

The latter led me to change a few tools, replace some things, and try some new work flows. Not all of it was good. I could never get imv to do the things I can with feh for instance, but mostly it was good.

One thing I really wanted to do was avoid XWayland (which allows apps that need X11 to run under Wayland). Wherever I could I’ve opted for applications that run natively under Wayland. There’s nothing wrong with XWayland, that was just a personal goal, for fun.

Here’s my notes on making the transition to Wayland along with the applications I use most frequently.

Terminal

I do almost everything in the terminal. I write in Vim, email with mutt, read RSS feeds with newsboat, listen to music with mpd, and browse files with ranger.

I tested quite a few Wayland-native terminals and I really like Alacritty. Highly recommended. Kitty is another option to consider.

That said, I am sticking with urxvt for now. There are two problems for me with Alacritty. First off Vim doesn’t play well with the Wayland clipboard in Alacritty. Second, Ranger will not show image previews in Alacritty.

Update April 2021: I have never really solved either of these issues, but I switched to Alacritty anyway. I use Neovim instead of Vim, which was a mostly transparent switch and Neovim support the Wayland clipboard. As for previews in Ranger… I forgot about those. They were nice. But I guess I don’t miss them that much.

Launcher

I’ve always used dmenu to launch apps and grab passwords from pass. It’s simple and fast. Unfortunately dmenu is probably never going to run natively in Wayland.

I tested rofi, wofi, and other potential replacements, but I did not like any of them. Somewhere in my search for a replacement launcher I ran across this post which suggested just calling up a small terminal window and piping a list of applications to fzf, a blazing fast search tool.

That’s what I’ve done and it works great. I created a keybinding to launch a new instance of Alacritty with a class name that I use to resize the window. Then within that small Alacritty window I call compgen to get a list of executables, then sort it to eliminate duplicates, and pass the results to fzf. Here’s the code in my Sway config file:

bindsym $mod+Space exec alacritty --class 'launcher' --command bash -c 'compgen -c | sort -u | fzf | xargs -r swaymsg -t command exec'

for_window [app_id="^launcher$"] floating enable, border none, resize set width 25 ppt height 20 ppt, move position 0 px 0 px

These lines together will open a small terminal window in the upper left corner of the screen with a fzf search interface. I type, for example, “dar” and Darktable comes up. I hit return, the terminal window closes, and Darktable launches. It’s as simple as dmenu and requires no extra applications (since I was already using fzf in Vim).

If you don’t want to go that route, Bemenu is dmenu-like launcher that runs natively in Wayland.

Browsers

I mainly use qutebrower, supplemented by Vivaldi² for research because having split screen tabs is brilliant for research. I also use Firefox Developer Edition for any web development work, because the Firefox dev tools are far superior to anything else.

All three work great under Wayland. In the case of qutebrowser though you’ll need to set a few shell variables to get it to start under Wayland, out of the box it launches with XWayland for some reason. Here’s what I added to .bashrc to get it to work:

export XDG_SESSION_TYPE=wayland 
export GDK_BACKEND=wayland

One thing to bear in mind if you do have a lot of X11 apps still is that with this in your shell you’ll need to reset the GDK_BACKEND to X11 or those apps won’t launch. Instead you’ll get an error, Gtk-WARNING **: cannot open display: :0. To fix that error you’ll need to reset GDK_BACKEND=x11, then launch your X11 app.

There are several ways you can do this, but I prefer to override apps in ~/bin (which is on my $PATH). So, for example, I have a file named xkdenlive in ~/bin that looks like this:

#! /bin/sh
GDK_BACKEND=x11 kdenlive

Note that for me this is easier, because the only apps I’m using that need X11 are Kdenlive and Slack. If you have a lot of X11 apps, you’re probably better off making qutebrowser the special case by launching it like this:

GDK_BACKEND=wayland qutebrowser

Clipboard

I can’t work without a clipboard manager, I keep the last 200 things I’ve copied, and I like to have things permanently stored as well.

Clipman does a good job of saving clipboard history.

You need to have wl-clipboard installed since Clipman reads and writes to and from that. I also use wofi instead of the default dmenu for viewing and searching clipboard history. Here’s how I set up clipman in my Sway config file:

exec wl-paste -t text --watch clipman store --max-items=60 --histpath="~/.local/share/clipman.json"
bindsym $mod+h exec clipman pick --tool="wofi" --max-items=30 --histpath="~/.local/share/clipman.json"

Clipman does not, however, have a way to permanently store bits of text. That’s fine. Permanently stored bits of frequently used text are really not all that closely related to clipboard items and lumping them together in a single tool isn’t a very Unix-y approach. Do one thing, do it well.

For snippets I ended up bending pet, the “command line snippet manager” a little and combining it with the small launcher-style window idea above. So I store snippets in pet, mostly just printf "my string of text", call up an Alacritty window, search, and hit return to inject the pet snippet into the clipboard. Then I paste it were I need it.

Volume Controls

Sway handles volume controls with pactl. Drop this in your Sway config file and you should be good:

bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle

Brightness

I like light for brightness. Once it’s installed these lines from my Sway config file assign it to my brightness keys:

bindsym --locked XF86MonBrightnessUp exec --no-startup-id light -A 10
bindsym --locked XF86MonBrightnessDown exec --no-startup-id light -U 10

Quirks, Annoyances And Things I Haven’t Fixed

There have been surprisingly few of these, save the Vim and Ranger issues mentioned above.

I haven’t found a working replacement for xcape. The only thing I used xcape for was to make my Cap Lock key dual-function: press generates Esc, hold generates Control. So far I have not found a way to do this in Wayland. There is ostensibly caps2esc, but it’s poorly documented and all I’ve been able to reliably do with it is crash Wayland.

Update April 2021: I managed to get caps2esc working. First you need to install it, for Arch that’s something like:

yay -S interception-caps2esc

Once it’s installed you need to create the config file. I keep mine at /etc/interception/udevmon.d/caps2esc.yaml. Open that up and paste in these lines:

- JOB: "intercept -g $DEVNODE | caps2esc | uinput -d $DEVNODE"
  DEVICE:
    EVENTS:
      EV_KEY: [KEY_CAPSLOCK, KEY_ESC]

Then you need to start and enable the udevmon service unit, which is what runs the caps2esc code:

sudo systemctl start udevmon
sudo systemctl enable udevmon

The last thing to do is restart. Once you’ve rebooted you should be able to hold down caps_lock and have it behave like control, but a quick press with give you escape instead. This is incredibly useful if you’re a Vim user.

The only other problems I’ve run into is the limited range of screen recording options — there’s wf-recorder and that’s about it. It works well enough though for what I do.

I’ve been using Sway exclusively for a year and half now and I have no reason or desire to ever go back to anything else. The rest of my family isn’t fond of the tiling aspect of Sway so I do still run a couple of laptops with Openbox. I’d love to see a Wayland Openbox clone that’s useable. I’ve played with labwc, which is promising, but lacks a tint2-style launcher, which is really what I need (i.e., a system tray with launcher buttons, which Waybar does not have). Anyway, I am keeping an eye on labwc because it looks like a good project.

That’s how I did it. But I am just one person. If you run into snags, feel free to drop a comment below and I’ll see if I can help.

Helpful pages:

• Sway Wiki: A good overview of Sway, config examples (how to replicate things from i3), and application replacement tips for i3 users (like this fork of redshift with support for Wayland).
• Arch Wiki Sway Page: Another good Sway resource with solutions to a lot of common stuff: set wallpaper, take screenshots, HiDPI, etc.
• Sway Reddit: There’s some useful info here, worth searching if you run into issues. Also quite a few good tips and tricks from fellow Sway users with more experience.
• Drew Devault’s Blog: He doesn’t always write about Sway, but he does give updates on what he’s working on, which sometimes has details on Sway updates.