Sway
Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.
Prerequisites
- Internet connectivity, unless the packages have been pre-fetched into a local cache.
- Install appropriate Graphics driver drivers for your hardware. Without graphics drivers errors are likely to occur.
- A non-root user account.
- The community repositories must be enabled.
- Set up eudev.
- Wayland compositors need raw access to input and output devices, typically mediated by a seat manager. Either seatd or elogind work fine, but installing both leads to conflicts.
Setup-desktop
The setup-desktop command automates the Sway desktop installation with eudev and elogind.
# setup-desktop sway
Proceed to the Starting Sway section, as no display manager is being installed nor configured by the script that would boot into a graphical login screen.
Manual Installation
The installation steps below allow you to pick and choose various components for your Sway desktop.
Install Fonts
Install DejaVu fonts (font-dejavu), which have good Unicode coverage:
# apk add font-dejavu
Install Sway
# apk add sway \ xwayland \ # if you need the xserver foot \ # default terminal emulator. Modify $term in config for a different one. wmenu \ # default Wayland native menu for choosing program and screensharing monitor swaylock swaylockd \ # lockscreen tool swaybg \ # display wallpaper grim \ # screenshot tool wl-clipboard \ # clipboard management i3status \ # simple status bar swayidle # idle management (DPMS) daemon
For complimentary software alternatives, see Sway's wiki or Gentoo's wiki.
Starting Sway
Manually Launch Sway
You can launch Sway manually by issuing the sway command from a TTY.
$ sway
sway with dbus-run-session, a convenient wrapper that will explicitly export the path of the session bus.$ dbus-run-session sway
Automatically Launch Sway on tty1
Adding the following lines to ~/.profile or to its equivalent will ensure that sway launches automatically, with a D-Bus, only from tty1. This is handy for troubleshooting, because if the Sway configuration ever falters, one could troubleshoot by logging into a different TTY (tty2-tty6), and your startup script then will not attempt to launch the faulty Sway environment from there also.
Contents of ~/.profile
Using a Wrapper Script to Launch Sway
Instead of using ~/.profile or its equivalent file, a wrapper script can be placed at /usr/local/bin/sway-run. This script can be used to launch sway from either a TTY or by greetd, a lightweight display manager, as follows:
Contents of /usr/local/bin/sway-run
Make the file executable:
# chmod +x /usr/local/bin/sway-run
Configuration
Sway config File
Copy the default Sway configuration file to ~/.config/sway/config so that it can be customized as per each user's choices:
$ mkdir -p ~/.config/sway $ cp /etc/sway/config ~/.config/sway/
Read through it to learn the default keybindings. Sway's configuration is mostly backward compatible with that of i3's, and if you are looking for a solution for a specific issue, you could try checking whether it hasn't been provided for the i3 window manager.
For additional information, start at man 5 sway and read the upstream wiki.
PipeWire and Screensharing
The Sway compositor has no involvement with audio playback. In order for screensharing to work, PipeWire is required. Therefore, installing PipeWire is recommended for audio playback too.
Since v3.22, Alpine Linux provides the necessary scripts to start PipeWire as a user service in OpenRC. Alternatively, PipeWire can be launched with Sway by adding the following line to Sway's config file:
exec /usr/libexec/pipewire-launcher
From a screensharing perspective, applications are split into two categories:-
- Those which use the native Wayland wlr-screencopy protocol
- Those which use the API from Flatpak's
xdg-desktop-portal(this portal is also used by native non-Flatpak applications).
Applications in the first group require no additional setup. Applications in the second group (which include Firefox and Chromium) require setting up xdg portals in addition to PipeWire.
# apk add xdg-desktop-portal xdg-desktop-portal-wlr
If you are using a dbus-run-session wrapper to launch Sway, you will also need to set D-Bus variables in order for the portal and for screensharing features to work; add the following line to the beginning of Sway's config file:
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
Screen Lock and suspend-to-RAM
Putting the system to sleep with the loginctl suspend command from Elogind requires elevated privileges or additional configuration.
To put the system to sleep after 600 seconds, use:
exec swayidle -w timeout 600 'doas /bin/loginctl suspend'
Do not lock the screen if program is running in full screen:
for_window [app_id="^.*"] inhibit_idle fullscreen
wayland-pipewire-idle-inhibit, needs to be tested. If you find the option below to be working, please remove this Todo.
If you do not want to lock the screen while media is being played through PipeWire, then install the wayland-pipewire-idle-inhibit package, and add the following to Sway's config file:
exec wayland-pipewire-idle-inhibit
Make changes to the ~/.config/wayland-pipewire-idle-inhibit/config.toml configuration file or to whichever configuration file you may have referenced instead through the --config <PATH>, if required, as per the project's website.
Elogind and swayidle
swayidle has integration with elogind, and it can handle before-sleep events.
If using swayidle before-sleep, then there will be a race condition, so that when you resume the computer from suspend, the screen will show the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.
To solve this issue, do the following.
Create the /etc/elogind/system-sleep/10-swaylock.sh file, and then add the following script to this file:
Contents of /etc/elogind/system-sleep/10-swaylock.sh
Then set it to executable.
Later, once Sway is installed, add the following line to its config file:
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep
With this line, the screen will be promptly locked before suspend-to-RAM starts.
Brightness Control
Refer to Backlight for information on brightness control.
Output Scaling for High Resolution Displays
Without further configuration, program interfaces may be too small to use on high resolution displays.
Sway supports the per-display configuration of:-
- fractional (e.g. 1.5x); and
- integer scaling (e.g. 2x)
However, fractional scaling is discouraged due both to the performance impact and to 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 toolkit scaling is recommended. See See below.
Scaling with wdisplays
To enable Sway scaling, the user can first preview different scaling factors with the 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 the following line, completed with your settings, to Sway's config file.
output <name> scale <factor>
Toolkit Scaling
To use toolkit scaling, say, at x2, add the following, for instance, to your ~/.profile:
# 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"
Notification Daemon
mako is a lightweight notification daemon that works seamlessly with Sway.
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 Sway's wiki article for a listing of further screenshot tools.
Make Clipboard Content Persistent
By default, the clipboard content does not persist after terminating the program: if you copy some text from Firefox and then exit Firefox, then the copied text is also lost.
Install clipman from the community repo, and then add the following to Sway's config file:
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 configuration 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
Start with NumLock Enabled
Add the following to your Sway config file:
input type:keyboard xkb_numlock enabled
Change mouse cursor theme and size
Add to your Sway config file:
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
For example, set a mouse cursor using the GNOME Adwaita theme:
seat seat0 xcursor_theme Adwaita 16
You can inspect their values with echo $XCURSOR_SIZE and echo $XCURSOR_THEME. If reloading your configuration does not result in change, try logging out and in.
$XCURSOR_SIZE and $XCURSOR_THEME.Custom Keyboard Layout
To use a custom keyboard layout, just use:
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
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 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 similar to those shown in the Firefox screensharing section above. For example, an autostart section in 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
These instructions are only needed if these backends are not started automatically via other means.
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 configuration files with git (if and when you use a remote repository for them, keep it private, for security reasons).
To capture the Sway error log in a file for troubleshooting, replace sway in your startup file by:
sway -d 2> ~/sway_error.log
Alternatively, you can also issue the below command from TTY.
$ sway -d 2> ~/sway_error.log
Video Driver Issues
After installing Sway, and while launching it for the first time, a lack of appropriate video drivers may cause various error messages such as:
- "unable to create backend"
- "Failed to create renderer"
Install the necessary drivers in order for your graphics card to work with Sway.
XDG_RUNTIME_DIR is not set in the environment. Aborting
If seatd is used instead of elogind, the error message XDG_RUNTIME_DIR is not set in the environment. Aborting might be encountered.
Ensure that the mandatory steps outlined in the Seatd wiki page are completed in order to set the XDG_RUNTIME_DIR variable.
No backend was able to open a seat
If no seat manager is available, then the error below will appear.
[libseat] [libseat/libseat.c:73] libseat_open_seat : No backend was able to open a seat [backend/session/libseat.c:102] Unable to create seat : Function not implemented [backend/backend.c:303] Failed to open any DRM device [sway/server.c:49] Unable to create backend
Ensure that either Elogind or Seatd is properly configured and running.
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, one could install an icon theme package for all users.
Missing file picker/cannot download
Go to about:config and set widget.use-xdg-desktop-portal.file-picker to 0.
Nvidia Issues
 This section is partly outdated and could benefit from contributions in view of Nvidia's current support of Wayland. Help is encouraged. |
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).