Sway

This page contains changes which are not marked for translation.

Resources

Sway (contracted from SirCmpwn's Wayland compositor) is an open-source Wayland compositor that is designed to be compatible with the i3 window manager.

Installation

USE flags

USE flags for gui-wm/sway i3-compatible Wayland window manager

`X`	Enable support for X11 applications (XWayland)
`grimshot`	Install 'grimshot': script for taking screenshots
`man`	Build and install man pages
`swaybar`	Install 'swaybar': sway's status bar component
`swaynag`	Install 'swaynag': shows a message with buttons
`tray`	Enable support for StatusNotifierItem tray specification
`wallpapers`	Install sway's default wallpaper image

Data provided by the Gentoo Package Database · Last update: 2023-03-12 22:26 More information about USE flags

Emerge

root #emerge --ask gui-wm/sway

Configuration

To view all available configuration options:

user $man 5 sway

Files

Each user running sway can edit the default configuration file in order to run a customized sway session. Gentoo stores this file at its default /etc/sway/config location:

user $

mkdir -p ~/.config/sway/

user $

cp /etc/sway/config ~/.config/sway/

Terminal emulator

By default the Sway configuration file uses the foot terminal emulator (found in the gui-apps/foot package). It is a good idea to emerge this terminal emulator so that a terminal will be available once Sway is running:

root #emerge --ask gui-apps/foot

Other popular choices include x11-terms/alacritty or x11-terms/kitty, which works natively with Wayland if the KITTY_ENABLE_WAYLAND environment variable is set to 1.

Another very lightweight alternative is st, but it isn't Wayland native.

Status bar

In addition to Sway's own status bar, gui-apps/waybar can be used as a highly customizable status bar for Sway:

root #emerge --ask gui-apps/waybar

Brightness

dev-libs/light can be used to adjust backlights and brightness. Here is an example config:

FILE ~/.config/sway/configSet the keyboard shortcuts for screen brightness support

bindsym XF86MonBrightnessDown exec light -U 2
bindsym XF86MonBrightnessUp exec light -A 4

Alternatively, sys-power/acpilight can also accomplish the same brightness changes via a xbacklight compatible command:

FILE ~/.config/sway/configSet the keyboard shortcuts for screen brightness support

bindsym XF86MonBrightnessDown exec xbacklight -dec 2
bindsym XF86MonBrightnessUp exec xbacklight -inc 4

Sound volume

If pulseaudio is being used, the following configuration can be used for changing sound volume:

FILE ~/.config/sway/configSet the keyboard shortcuts to change sound volume for pulseaudio

bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%

If PipeWire is being used, the following configuration can be used for changing sound volume (with Wireplumber):

FILE ~/.config/sway/configSet the keyboard shortcuts to change sound volume for PipeWire

bindsym XF86AudioRaiseVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
bindsym XF86AudioLowerVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-

If ALSA is being used, the following configuration can be used for changing the sound volume:

FILE ~/.config/sway/configSet the keyboard shortcuts to change sound volume for ALSA

bindsym XF86AudioRaiseVolume exec amixer -Mq set Speaker 5%+
bindsym XF86AudioLowerVolume exec amixer -Mq set Speaker 5%-

If media-sound/sndio is being used, the following configuration can be used for changing the sound volume:

FILE ~/.config/sway/configSet the keyboard shortcuts to change sound volume for sndio

bindsym XF86AudioRaiseVolume exec sndioctl -f snd/default output.level=+0.05
bindsym XF86AudioLowerVolume exec sndioctl -f snd/default output.level=-0.05

Taking screenshots

To add screenshot support, use the grim utility (found in the gui-apps/grim package). The abbreviation grim is defined as Grab Images. This utility is tailored to the specifics of the Wayland protocol. In order to install grim, use the following command:

root #emerge --ask gui-apps/grim

To add support for determining the boundaries of the selected screen area, the slurp utility, found in the gui-apps/slurp package, is used in combination with the grim utility. To install slurp, use the command:

root #emerge --ask gui-apps/slurp

Next, edit the configuration file to add support for keyboard shortcuts to perform a screenshot operation:

FILE ~/.config/sway/configSet the keyboard shortcuts for screenshot support

#
# Screen capture
#
set $ps1 Print
set $ps2 Control+Print
set $ps3 Alt+Print
set $ps4 Alt+Control+Print
set $psf $(xdg-user-dir PICTURES)/ps_$(date +"%Y%m%d%H%M%S").png
 
bindsym $ps1 exec grim - | wl-copy
bindsym $ps2 exec grim -g "$(slurp)" - | wl-copy
bindsym $ps3 exec grim $psf
bindsym $ps4 exec grim -g "$(slurp)" $psf

Please note that the Print or Ctrl + Print keys combination creates a screenshot in the wl-copy buffer. This allows pasting the image directly from the clipboard, without having to save to a file on disk.

For the Alt + Print or Alt + Ctrl + Print keyboard shortcuts, the method of automatically saving the image file in the Pictures user directory is used.

Set a random wallpaper

A random wallpaper can be pulled from a folder and be set: ^[1]

FILE ~/.config/sway/configSet a random wallpaper from a folder

set $wallpapers_path $HOME/Pictures/Wallpapers
output * bg $(find $wallpapers_path -type f | shuf -n 1) fill

Run application when the system gets idle

Package gui-apps/swayidle runs a command after a certain idle time, usually to lock and power off the screen. To use swayidle, emerge gui-apps/swayidle and include the corresponding code in sway configuration file. For example, to power off the sway outputs after fifteen minutes of system idle:

root #emerge --ask gui-apps/swayidle

FILE ~/.config/sway/configPower off Screens when Idle

exec swayidle -w \
  timeout 900 'swaymsg "output * power off"' \
  resume 'swaymsg "output * power on"'

HiDPI

To adjust sway's rendering for HiDPI displays (4K and above), the name of the display to be adjusted must be obtained. After a sway session is running, issue the following:

user $swaymsg -t get_outputs

Note
The swaymsg USE flag must be enabled for the swaymsg command to be available on the system.

The output statement in the sway configuration file will accept a scale parameter to adjust the scaling of the high resolution display.

Executing sway

Some display managers may work but are not supported by sway.^[2] Without a display manager involved sway can be started from a tty:

user $dbus-run-session sway

Omitting the dbus-run-session may cause runtime errors.

Systems that are configured with neither systemd nor elogind will need to create a bash script (or use some other means) to set the XDG_RUNTIME_DIR variable.

Note
The instructions below must be followed only if the environment does not define the XDG_RUNTIME_DIR variable (this is usually the case, if systemd/elogind are not used).

The environment variable can be defined in the usual configuration files. For example, if Larry the cow (Larry) sets XDG_RUNTIME_DIR variable in his Bash shell's configuration file and he has chosen that the directory will be in /tmp:

FILE /home/larry/.bash_profileSet the XDG_RUNTIME_DIR variable

#!/bin/bash
if test -z "${XDG_RUNTIME_DIR}"; then
    export XDG_RUNTIME_DIR=/tmp/${UID}-runtime-dir
    if ! test -d "${XDG_RUNTIME_DIR}"; then
        mkdir "${XDG_RUNTIME_DIR}"
        chmod 0700 "${XDG_RUNTIME_DIR}"
    fi
fi

With the XDG_RUNTIME_DIR defined, sway can be launched as usual:

user $dbus-run-session sway

If issues are encountered, check Sway issues on GitHub before contacting the Sway community on IRC (#sway (webchat)) or opening a new Gentoo bug.

Launching Sway from a script

This method uses a script to forcibly take over a virtual terminal and launch Sway in it. The typical use case is to launch Sway automatically on boot.

Note
Sway is not supposed to be launched this way, the script may need some tuning to work.

FILE /usr/sbin/sway_launcherSway Launcher

#!/bin/sh

# Launch sway with a specific user, from a specific Virtual Terminal (vt)
# Two arguments are expected: a username (e.g., larry) and the id of a free vt (e.g., 7)

# prepare the tty for the user. vtX uses /dev/ttyX
chown "$1" "/dev/tty${2}"
chmod 600 "/dev/tty${2}"

# setup a clean environment for the user, take over the target vt, then launch sway
su --login --command "openvt --switch --console ${2} -- sway >\${HOME}/.sway_autolauncher.log 2>&1" "$1"
# this script returns immediately

This script has a few limitations:

XDG_RUNTIME_DIR is expected to be defined and valid, see the section above.
Without the --switch option for openvt, sway will freeze when trying to switch to a different vt (Ctrl+Alt+Fn), whether this is a bug or not is unknown.
The vt is not cleared when Sway exits, clear it by calling deallocvt.
Similarly the tty's owner and mode are not changed back to their default values when Sway exits.

Launching this script on boot can be done with the local service:

FILE /etc/local.d/sway.startLaunch Sway on boot

#!/bin/sh
sway_launcher larry 7

Usage

All key combinations will be defined in the ~/.config/sway/config configuration file.

The Super key is defined as the $mod value by default. On most keyboards this will be the Windows key.

Movement

Sway has a Vi-like interface. h (left), j (down), k (up), and l (right) can be used for movement.

See man 5 sway-input for more information.

Terminal

The default key combination to open a terminal emulator is $mod+Enter.

GTK theme and font

Currently setting a GTK font and theme should be done by editing sway's configuration file (see Sway's wiki as well):

FILE ~/.config/sway/configSet the font and theme for GTK applications

set $gnome-schema org.gnome.desktop.interface
exec_always {
    gsettings set $gnome-schema gtk-theme 'theme name'
    gsettings set $gnome-schema icon-theme 'icon theme name'
    gsettings set $gnome-schema cursor-theme 'cursor theme name'
    gsettings set $gnome-schema font-name 'Sans 10'
}

If encountering problems setting the mouse cursor with certain applications (including sway), this may help:

FILE ~/.config/sway/configSet the cursor theme

seat seat0 xcursor_theme custom_cursor_theme custom_cursor_size

Replace custom_cursor_theme and custom_cursor_size. Adwaita and 24 are pretty much default on all Linux distros.

Troubleshooting

Screen sharing does not work

Make sure the package gui-libs/xdg-desktop-portal-wlr is installed. By default, it is autostarted by D-Bus but it fails to run because it needs environment variables exported by Sway, and the D-Bus session is started before Sway. To fix, update the D-Bus environment by adding the following line to the beginning of Sway's config:

FILE ~/.config/sway/config

exec --no-startup-id dbus-update-activation-environment --all

Also see this link to see if PipeWire is working properly. Note that, as of April 2022, screenshotting/screensharing is not yet implimented in wlroots/sway with the vulkan renderer (See this issue)

Failed to connect to user bus

[swaybar/tray/tray.c:42] Failed to connect to user bus: No such file or directory

Forum topic [swaybar/tray/tray.c:42] Failed to connect to user bus: No such file or directory => Use dbus-run-session sway
Forum topic sway(bar) with tray support
https://github.com/swaywm/sway/issues/1415

Warning: no icon themes loaded

[swaybar/tray/icon.c:348] Warning: no icon themes loaded

It is looking for x11-themes/hicolor-icon-theme

No backend was able to open a seat

 [ERROR] [wlr] [libseat] [libseat/libseat.c:78] No backend was able to open a seat

It is looking for a seat management daemon such as sys-auth/seatd or sys-auth/elogind. Also check whether setting XDG_RUNTIME_DIR is required.

Important
If sys-auth/seatd is used, USE=server is required.

Applications forget logins

Some applications (e. g. net-misc/nextcloud-client) use a Secret-Service-Agent to save credentials for login. If applications ask for account credentials every run, an incorrectly configured Secret-Service-Agent might be the reason.

First, emerge gnome-base/gnome-keyring.

root #emerge --ask gnome-base/gnome-keyring

Then, enable the gnome-keyring USE flag.

FILE /etc/portage/package.use

# Sway Secret-Service-Agent
*/* gnome-keyring

Update the system to apply the new USE flag.

root #emerge -avuDN @world

To run and unlock the Agent's storage when logging into a Sway session, edit these two files.