Sway
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 |
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:
~/.config/sway/config
Set the keyboard shortcuts for screen brightness supportbindsym 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:
~/.config/sway/config
Set the keyboard shortcuts for screen brightness supportbindsym 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:
~/.config/sway/config
Set the keyboard shortcuts to change sound volume for pulseaudiobindsym 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):
~/.config/sway/config
Set the keyboard shortcuts to change sound volume for PipeWirebindsym 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:
~/.config/sway/config
Set the keyboard shortcuts to change sound volume for ALSAbindsym 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:
~/.config/sway/config
Set the keyboard shortcuts to change sound volume for sndiobindsym 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:
~/.config/sway/config
Set 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]
~/.config/sway/config
Set a random wallpaper from a folderset $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
~/.config/sway/config
Power off Screens when Idleexec 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
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.
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:
/home/larry/.bash_profile
Set 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.
Sway is not supposed to be launched this way, the script may need some tuning to work.
/usr/sbin/sway_launcher
Sway 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:
/etc/local.d/sway.start
Launch 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):
~/.config/sway/config
Set the font and theme for GTK applicationsset $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:
~/.config/sway/config
Set the cursor themeseat 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:
~/.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.
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.
/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.
~/.config/sway/config
exec dbus-update-activation-environment --all exec gnome-keyring-daemon --start --components=secrets exec export $(gnome-keyring-daemon)
/etc/pam.d/login
auth optional pam_gnome_keyring.so password optional pam_gnome_keyring.so session optional pam_gnome_keyring.so auto_start
See also
- I3 — a minimalist tiling window manager, completely written from scratch.
- Wayland — a simpler and modern replacement for X display server.
- Weston — a reference implementation of a Wayland compositor.