Sway

Sway is a tiling Wayland compositor. It's a drop-in replacement for the i3 window manager.

Installation

Setting up eudev on a desktop system is recommended:

# setup-devd udev

For more details and advanced instructions see Device Manager.

Graphics drivers:

Adding your user account to the input and video groups is not required and discouraged by upstream. Sway will obtain access to input and video devices via seatd or elogind, whichever is available.

Install some TTF fonts:

# apk add font-dejavu

seatd daemon:

# apk add seatd # rc-update add seatd # rc-service seatd start # adduser $USER seat

Install sway:

# apk add sway # apk add \ # Install optional dependencies: xwayland \ # recommended for compatibility reasons foot \ # default terminal emulator. Modify $term in config for a different one. bemenu \ # wayland menu swaylock swaylockd \ # lockscreen tool swaybg \ # wallpaper daemon swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see for example this list at Gentoo Wiki.

Configure XDG_RUNTIME_DIR.

Usage

Applications such as Firefox or Chromium use Pipewire for screencasting. This requires installing D-Bus and PipeWire and running both as part of the user session. The SWAYSOCK environmental variable also needs to be set for Pipewire to the value exported by sway.

In order to ensure that Pipewire and related services inherit the right environment variables, it is recommended to start these services via a process that is a direct descendant of sway itself.

Launch Sway with a D-Bus server available, use:

dbus-run-session -- sway #prepend with exec in your login shell init script

Configuration

An example config is provided at /etc/sway/config. Copy it to ~/.config/sway/config and read through it to learn the default keybindings. Sway configuration is mostly backwards-compatible with that of i3 and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at man 5 sway and read the upstream wiki.

Firefox screensharing

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

Install and configure PipeWire
Install xdg-desktop-portal and xdg-desktop-portal-wlr package
Install wofi for screen selection
Launch pipewire on sway startup:

exec /usr/libexec/pipewire-launcher

xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Unless dbus-daemon is a descendant of the sway process, add to the sway config:

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

Export the following variables:

export MOZ_ENABLE_WAYLAND ="1" export XDG_CURRENT_DESKTOP=sway export QT_QPA_PLATFORM="wayland-egl"

Flatpaks

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see flatpak's page on the subject. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:

exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome

This is only needed if they are not started automatically via other means.

Scaling for high resolution screens

Without further configuration, program interfaces might be too small to use on high resolution screens.

Via sway

Sway supports the per-display configuration of

fractional (e.g., 1.5x), and
integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with wdisplays package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

output <name> scale <factor>

to ~/.config/sway/config.

Via GTK/Qt

# for GTK-based programs such as firefox and emacs: export GDK_DPI_SCALE=2 # for QT-based programs export QT_WAYLAND_FORCE_DPI="physical" # or if still too small, use a custom DPI export QT_WAYLAND_FORCE_DPI=192 # 2x scaling export QT_QPA_PLATFORM="wayland-egl"

Make clipboard content persistent

By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

~~Install clipman from testing repo and add the following to sway config:~~

Unfortunately, the clipman project has been abandoned and deleted from GitHub. Use cliphist instead, which is also available in the testing repository. See picker examples section on the project's page to add an appropriate keybinding line to your sway config.

exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"

Firefox picture-in-picture mode/floating windows

Add this to your sway config file (modify the numeric values to suit your needs and your display):

for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none

Screenshots

A simple tool that works well under Wayland is Grimshot. Example keybindings:

bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png

See the sway wiki's article for a list of screenshot tools.

Start with NumLock enabled

Add this to your sway config file: input type:keyboard xkb_numlock enabled

Change cursor theme and size

Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

You can inspect their values with echo $XCURSOR_SIZE and echo $XCURSOR_THEME. If reloading your config does not result in change, try logging out and in.

Note: Wayland uses client-side cursors. It is possible that applications do not evaluate the values of $XCURSOR_SIZE and $XCURSOR_THEME.

Start as a service

Although this is not necessary, you may write an init script like the following:

Contents of /etc/init.d/sway

{{{2}}}

Replace $USER with your user name.

Then run

# chmod +x /etc/init.d/sway

and

# rc-update add sway default

Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

Custom keyboard layout

Since wayland does not support setxkbmap, you will also need to add similar content to your /usr/share/X11/xkb/rules/evdev.xml, after </modelList> and after <layoutList>:

<layout>
      <configItem>
        <name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
        <shortDescription>[usually just two letters]</shortDescription>
        <description>[description of your layout]</description>
        <countryList>
          <iso3166Id>US</iso3166Id>
          <iso3166Id>NO</iso3166Id>
        </countryList>
        <languageList>
          <iso639Id>eng</iso639Id>
        </languageList>
      </configItem>
    </layout>
<!--[other layouts]-->

Then, to enable for all keyboards, navigate to the input section of ~/.config/sway/config and modify it to

input * {
  xkb_layout "my_layout" 
}

If you have enabled xkb_numlock, include this setting inside those braces as well.

Troubleshooting

If you encounter any issues, try running sway -Vc /etc/sway/config. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

Firefox (Flatpak) and/or GTK apps

Disappearing cursor

You may need to get an icon pack and possibly a theme from Pling store and set GTK_THEME environmental variable. Alternatively you can install a theme for all users (search Alpine Linux Packages for *-icon-theme) using apk add.

Missing file picker/cannot download

Go to about:config and set widget.use-xdg-desktop-portal.file-picker to 0.

Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start

As of Dec 31 2022, Nvidia still doesn't fully support Wayland. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to drm,libinput or x11 (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards (make sure to install libinput first).

Sway socket not detected

See Installation for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as tmux

Steam games launched via Proton crash before creating a window

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing proton-ge-custom, but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your privacy.