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)
filecaps Use Linux file capabilities to control privilege rather than set*id (this is orthogonal to USE=caps which uses capabilities at runtime e.g. libcap)
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


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 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.

Display configuration

Display options can be queried with:

user $swaymsg -t get_outputs
Output DP-1 'HP Inc. HP X34 6CM2261GK2' (focused)
  Current mode: 3440x1440 @ 165.000 Hz
  Position: 0,0
  Scale factor: 1.000000
  Scale filter: nearest
  Subpixel hinting: unknown
  Transform: normal
  Workspace: 1
  Max render time: off
  Adaptive sync: disabled
  Available modes:
    3440x1440 @ 165.000 Hz
Output DP-2 'LG Electronics LG HDR QHD 110NTTQ0U193'
  Current mode: 2560x1440 @ 59.951 Hz
  Position: 3440,0
  Scale factor: 1.000000
  Scale filter: nearest
  Subpixel hinting: unknown
  Transform: normal
  Workspace: 2
  Max render time: off
  Adaptive sync: disabled
  Available modes:
    2560x1440 @ 59.951 Hz
    2560x1440 @ 74.971 Hz
Output DP-3 'Ancor Communications Inc VE247 E3LMQS103610'
  Current mode: 1920x1080 @ 60.000 Hz
  Position: 6000,0
  Scale factor: 1.000000
  Scale filter: nearest
  Subpixel hinting: unknown
  Transform: normal
  Workspace: 3
  Max render time: off
  Adaptive sync: disabled
  Available modes:
    1920x1080 @ 60.000 Hz

The results have been shortened to only contain the desired resolution. The default positions are not configured properly, and can be adjusted by modifying ~/.config/sway/config. Once the file is saved, the configuration can be reloaded with $mod+Shift+C

FILE ~/.config/sway/configConfigure the left display which is physically slightly larger than the primary display
output DP-1 resolution 3440x1440@165hz pos 2560 350
FILE ~/.config/sway/configConfigure primary display which is centered
output DP-2 resolution 2560x1440@74.971hz pos 0 250
FILE ~/.config/sway/configConfigure alternate display which is vertical
output DP-3 resolution 1920x1080@60hz pos 6000 0 transform 270

Input Devices

Input devices can be queried with:

user $swaymsg -t get_inputs
Input device: Logitech G502 HERO Gaming Mouse Keyboard
  Type: Mouse
  Identifier: 1133:49291:Logitech_G502_HERO_Gaming_Mouse_Keyboard
  Product ID: 49291
  Vendor ID: 1133
  Libinput Send Events: enabled
Input device: Logitech G502 HERO Gaming Mouse Keyboard
  Type: Keyboard
  Identifier: 1133:49291:Logitech_G502_HERO_Gaming_Mouse_Keyboard
  Product ID: 49291
  Vendor ID: 1133
  Active Keyboard Layout: English (US)
  Libinput Send Events: enabled
Input device: Logitech G502 HERO Gaming Mouse
  Type: Mouse
  Identifier: 1133:49291:Logitech_G502_HERO_Gaming_Mouse
  Product ID: 49291
  Vendor ID: 1133
  Libinput Send Events: enabled
FILE ~/.config/sway/configDisable mouse acceleration, decrease pointer speed
input "1133:49291:Logitech_G502_HERO_Gaming_Mouse" {
    accel_profile "flat"
    pointer_accel -0.1

Application launcher

By default, Sway is configured to use dmenu, which uses X. dev-libs/bemenu is a good alternative that supports Wayland.

root #emerge --ask dev-libs/bemenu
FILE ~/.config/sway/configConfigure Sway to use bemenu
set $menu bemenu-run | xargs swaymsg exec --
FILE ~/.config/sway/configConfigure Sway to use bemenu with no prompt
set $menu bemenu-run -p "" | xargs swaymsg exec --

Status bar

In addition to Sway's own status bar, Waybar can be used as a highly customizable status bar for Sway:

root #emerge --ask gui-apps/waybar

This can be enabled with:

FILE ~/.config/sway/configEnable Waybar, hide the builtin bar
bar {
    status_command waybar
    mode invisible


FILE ~/.config/sway/configEnable Waybar
exec waybar


The github page for dev-libs/light currently (2023-09) states: "This project is considered orphaned since the 8th of March, 2023. Use is heavily discouraged until such a time that it is adopted by another developer.". The package currently remains in the Gentoo ebuild repository, but users may want to take the message from the dev into consideration.

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

Simple approach: use slurpshot

(Slurpshot) is a script to simplify taking screenshots. It uses native wayland apps only and enables selecting specific windows only, as well as previewing and printing screenshots withous saving them. First install dependencies:

root #emerge --ask gui-apps/grim gui-apps/slurp app-misc/jq dev-libs/bemenu

Put the slurpshot script somewhere in your PATH, for example to ~/bin, make it executable and just set one keybind:

FILE ~/.config/sway/configSet the keyboard shortcuts for slurpshot support
# Screen capture
bindsym Print exec slurpshot

Manual approach

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.

Snipping tool like behavior

The following captures an area of the screen to the clipboard when mod+shift+S is pressed:

FILE ~/.config/sway/configSimilar function to the snipping tool
bindsym $mod+shift+s exec grimshot copy area

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


gui-apps/swaylock can be used to lock the current session.

root #emerge --ask gui-apps/swaylock
FILE ~/.config/sway/configLock the session when $mod+l is pressed
bindsym $mod+l exec swaylock --ignore-empty-password --show-failed-attempts --color 1e1e1e
FILE ~/.config/sway/configWith colors man swaylock for more info
bindsym $mod+l exec swaylock --ignore-empty-password --show-failed-attempts \
    --color 1e1e1e --inside-color cccccc --ring-color ffffff \
    --inside-clear-color 11a8cd --ring-clear-color 29b8db \
    --inside-ver-color 2472c8 --ring-ver-color 3b8eea \
    --inside-wrong-color cd3131 --ring-wrong-color f14c4c
If the account is locked out, swaylock will not indicate this, and will simply fail. Switching to another TTY and attempting login can help diagnose this


gui-apps/swayidle runs a command after a certain idle time, typically to lock and/or power off the screen.

root #emerge --ask gui-apps/swayidle
FILE ~/.config/sway/configPower off all displays after 15 minutes of idle
exec swayidle -w \
  timeout 900 'swaymsg "output * power off"' \
  resume 'swaymsg "output * power on"'


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.


FILE ~/.config/sway/configReload ~/.Xresources on sway reload
exec_always test -f ~/.Xresources && xrdb -merge ~/.Xresources

GTK configuration

Dark Mode


GTK3 dark mode can be enabled by setting:

FILE ~/.config/gtk-3.0/config.iniEnable gtk3 dark mode
gtk-application-prefer-dark-theme = true

GTK2 does not have a dark mode toggle, a dark theme must be selected:

FILE ~/.gtkrc-2.0Enable gtk3 dark mode
gtk-theme-name = "Adwaita-dark"

GTK3 Themes and Fonts

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 distributions.

Automatic floating windows

By default, Sway opens new windows in tiling mode. The following configuration snippet makes many common windows which should float, float:

FILE ~/.config/sway/configMore reasonable floating windows[2]
for_window [window_role = "pop-up"] floating enable
for_window [window_role = "bubble"] floating enable
for_window [window_role = "dialog"] floating enable
for_window [window_type = "dialog"] floating enable
for_window [window_role = "task_dialog"] floating enable
for_window [window_type = "menu"] floating enable
for_window [app_id = "floating"] floating enable
for_window [app_id = "floating_update"] floating enable, resize set width 1000px height 600px
for_window [class = "(?i)pinentry"] floating enable
for_window [title = "Administrator privileges required"] floating enable

Firefox Tweaks

FILE ~/.config/sway/configMake relevant Firefox windows float[3]
for_window [title = "About Mozilla Firefox"] floating enable
for_window [window_role = "About"] floating enable
for_window [app_id="firefox" title="Library"] floating enable, border pixel 1, sticky enable
FILE ~/.config/sway/configRemove the sharing indicator window for Firefox[4]
for_window [title = "Firefox - Sharing Indicator"] kill
for_window [title = "Firefox — Sharing Indicator"] kill

Steam Tweaks

FILE ~/.config/sway/configMake Steam dialog windows float[5]
for_window [class="^Steam$" title="^Friends$"] floating enable
for_window [class="^Steam$" title="Steam - News"] floating enable
for_window [class="^Steam$" title=".* - Chat"] floating enable
for_window [class="^Steam$" title="^Settings$"] floating enable
for_window [class="^Steam$" title=".* - event started"] floating enable
for_window [class="^Steam$" title=".* CD key"] floating enable
for_window [class="^Steam$" title="^Steam - Self Updater$"] floating enable
for_window [class="^Steam$" title="^Screenshot Uploader$"] floating enable
for_window [class="^Steam$" title="^Steam Guard - Computer Authorization Required$"] floating enable
for_window [title="^Steam Keyboard$"] floating enable



On OpenRC based systems, elogind must be added to the boot runlevel:

root #rc-update add elogind boot


Starting Sway

Although not officially supported, some display managers may work with sway.[6]
Starting Sway with dbus requires that XDG_RUNTIME_DIR is set. elogind or systemd will set this if used. Omitting the dbus-run-session may cause runtime errors.

Launching Sway automatically with TTY login

To start Sway on login to the first TTY:

FILE ~/.bashrcLaunch Sway after logging into the first TTY
if [ -z "${WAYLAND_DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then
    dbus-run-session sway

Starting Sway manually

user $dbus-run-session sway

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, 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
sway_launcher larry 7

Starting Sway without elogind or systemd

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

The environment variable can be defined in the usual configuration files. For example, if Larry the cow (Larry) sets the XDG_RUNTIME_DIR variable in his 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
  UID="$(id -u)"
  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 (webchat)) or opening a new Gentoo bug.


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, in addition to the arrow keys.

Focus can be moved with mod+direction key, windows can be moved with mod+shift+direction key:

FILE ~/.config/sway/configDefault movement definitions
bindsym $mod+Left focus left
bindsym $mod+Down focus down
bindsym $mod+Up focus up
bindsym $mod+Right focus right
bindsym $mod+Shift+Left move left
bindsym $mod+Shift+Down move down
bindsym $mod+Shift+Up move up
bindsym $mod+Shift+Right move right

See man 5 sway-input for more information.

Useful binds

FILE ~/.config/sway/configCycle between workspaces with mod+control+left arrow and mod+control+right arrow
bindsym $mod+control+Right workspace next
bindsym $mod+control+Left workspace prev


By default, Sway uses a tiling layout. Layout modes can be switched with the following default binds:

  • mod+b - Horizontal split
  • mod+v - Vertical split
  • mod+s - Stacking
  • mod+w - Tabbed
  • mod+e - Toggle split
  • mod+shift+space - Toggle floating
FILE ~/.config/sway/configDefault layout definitions
bindsym $mod+b splith
bindsym $mod+v splitv
bindsym $mod+s layout stacking
bindsym $mod+w layout tabbed
bindsym $mod+e layout toggle split
bindsym $mod+Shift+space floating toggle


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

Foot Server

Foot is a minimal Wayland terminal emulator that can be configured to run as a server, reducing resource usage.

FILE ~/.config/sway/configStart the Foot server with Sway
exec foot -s
FILE ~/.config/sway/configSet the default terminal to be a foot client
set $term footclient
If starting the foot server with Sway, it may not start fast enough to also auto-start a service, exec swaymsg "workspace 2; exec $term {command}" may be slow enough to mitigate this

Adding features

Sway is designed to be extended, adding additional features is easy:

FILE ~/.config/sway/configStart htop when control+shift+esc is pressed
bindsym control+shift+escape exec $term htop

If using foot, the app_id, which is set with -a, can be set to make it float automatically:

FILE ~/.config/sway/configStart htop floating when control+shift+esc is pressed
bindsym control+shift+escape exec $term -a 'flying-foot' htop
for_window [app_id="flying-foot"] floating enable


Screen sharing does not work

Ensure sys-apps/xdg-desktop-portal is built with the screencast USE flag.

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. Ensure XDG_CURRENT_DESKTOP=sway.

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

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.

If sys-auth/seatd is used, the server USE flag 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.

FILE ~/.config/sway/config
exec dbus-update-activation-environment --all
exec gnome-keyring-daemon --start --components=secrets
exec export $(gnome-keyring-daemon)
FILE /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 replacement for the X11 window system protocol and architecture with the aim to be easier to develop, extend, and maintain
  • Weston — a reference implementation of a Wayland compositor.