From Gentoo Wiki
Jump to:navigation Jump to:search

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


USE flags

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

X Enable support for X11 applications (XWayland)
elogind Enable support for rootless session via elogind
fish-completion Enable fish completion support
man Build and install man pages
seatd Enable support for rootless session via sys-auth/seatd
swaybar Install 'swaybar': sway's status bar component
swaybg Install 'swaybg': allows to set a desktop background image
swayidle Install 'swayidle': idle manager to run commands when user is inactive
swaylock Install 'swaylock': sway's screen locker
swaymsg Install 'swaymsg': tool for communicating with a running sway instance
swaynag Install 'swaynag': shows a message with buttons
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
tray Enable support for StatusNotifierItem tray specification
wallpapers Install sway's default wallpaper image
zsh-completion Enable zsh completion support


root #emerge --ask gui-wm/sway


To view all available configuration options:

user $man 5 sway


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 Alacritty terminal emulator (found in the x11-terms/alacritty 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 x11-terms/alacritty

Another popular choice is 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


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
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%

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
bindsym $ps1 exec grim - | wl-copy
bindsym $ps2 exec grim -g "$(slurp)" - | wl-copy
bindsym $ps3 exec grim $(xdg-user-dir PICTURES)/ps_$(date +"%Y%m%d%H%M%S").png
bindsym $ps4 exec grim -g "$(slurp)" $(xdg-user-dir PICTURES)/ps_$(date +"%Y%m%d%H%M%S").png

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


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.

FILE /home/larry/.bash_profileSet the XDG_RUNTIME_DIR variable
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}"

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) 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.
FILE /usr/sbin/sway_launcherSway Launcher

# 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, you can do 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
sway_launcher larry 7


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.


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.


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'


Failed to connect to user bus

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

Warning: no icon themes loaded

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

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

See also

External resources