From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

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
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
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 urxvt terminal emulator (found in the x11-terms/rxvt-unicode 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/rxvt-unicode

Another popular choice is x11-terms/kitty which works natively with Wayland if the KITTY_ENABLE_WAYLAND environment variable is set to 1. Users wanting more a barebone, Wayland native, terminal emulator may want to test out Alacritty. Another very lightweight alternative is st, but it isn't Wayland native.


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


If using ConsoleKit (OpenRC), run Sway using:

user $exec ck-launch-session sway


When using Systemd or Elogind Sway can be launched with:

user $sway


Systems that are configured with neither systemd, elogind, nor ConsoleKit, 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/consolekit 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 $sway

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


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

The 'logo' 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.

See also