Drew DeVault edited this page Aug 8, 2018 · 138 revisions


Sway is NOT an X11 window manager! It does not work like one. Please read the documentation carefully when configuring it.

Before installing

Nvidia users

All proprietary graphics drivers are unsupported. This includes the Nvidia proprietary driver - the open source Nouveau drivers required. This is not going to change, don't ask. Tip: buy your hardware with open source support in mind.

Login managers

Some login managers support Wayland, others don't, and none are supported by Sway. (Discussion related to login managers is not tolerated on support channels.) It's recommended that you simply login at a getty and run sway from the shell, or configure a .bashrc or similar to start sway upon logging into the getty.

For example. In order to start Sway automatically after logging into tty1, one can place the following into their .bashrc:

# If running trom tty1 start sway
if [ $(tty) = "/dev/tty1" ]; then
	exit 0


The suggested location for the sway configuration file is ~/.config/sway/config. To begin configuring sway, create this directory and copy the default config.

mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/
$EDITOR ~/.config/sway/config

Read man 5 sway for more information about the config.

Display configuration

Sway manages displays for you, xrandr should not be used.

Run swaymsg -t get_outputs to get a list of output names. Then use the output command to arrange your displays.

For detailed information, check the manual. Run man 5 sway and search for output.


Managing multiple monitors is simple through the use of multiple output commands.

e.g., if we want to have a monitor with <name> HDMI1 and a resolution of 1920x1080, and to the right of it a laptop monitor with <name> eDP1 and a resolution of 1600x900; the following two commands can be placed in our config file.

output HDMI1 pos 0 0 res 1920x1080
output eDP1 pos 1920 0 res 1600x900


HiDPI can be enabled via output and its scale option.

output <name> scale <I>

<I> is the integer scaling factor (usually 2 for HiDPI screens)

If scaling is active, it has to be considered when defining relative positions. For example, if the scaling factor for the left monitor (HDMI1) is 2, the relative position for the right output has to be divided by 2. This example is illustrated by the configuration below:

output HDMI1 scale 2
output HDMI1 pos 0 0 res 3200x1800
output eDP1 pos 1600 0 res 1920x1080

Note that the x-pos of eDP1 is 1600 = 3200/2.

Display rotation

Rotation is not currently supported. This needs to be implemented in WLC. See https://github.com/Cloudef/wlc/issues/86.

Input configuration

Keyboard layout

You have to set the keyboard layout before starting sway, using environmental variables such as XKB_DEFAULT_LAYOUT=de sway. It is also possible to set other options known from setxkbmap with the environment variables XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT, XKB_DEFAULT_OPTIONS. To set these options, it is best to launch sway with a script.

In the following example, right before launching sway, this script sets environment variables that enable switching between the American and German layouts, without dead keys, using the hotkey Alt-Shift:

export XKB_DEFAULT_VARIANT=,nodeadkeys
export XKB_DEFAULT_OPTIONS=grp:alt_shift_toggle,

Supported parameters are defined in /usr/share/X11/xkb/symbols/*.

  • Make caps lock work as escape: export XKB_DEFAULT_OPTIONS=caps:escape
  • Swap escape and caps lock: export XKB_DEFAULT_OPTIONS=caps:swapescape
  • Make caps lock work as control: export XKB_DEFAULT_OPTIONS=ctrl:nocaps

Keyboard repeat delay and rate

Set the environment variables WLC_REPEAT_DELAY/WLC_REPEAT_RATE to the delay/rate in milliseconds before starting sway.

Input device configuration

Run swaymsg -t get_inputs to find the name of the input device that you want to configure, then add an input section to your config. Example config:

input <device name> {
    tap enabled
    natural_scroll disabled
    dwt enabled

See man sway-input for all available options.


Feh and similar tools do not work on Wayland. Sway supports setting wallpapers through the output command, using the bg option:

e.g., output HDMI-A-1 bg ~/wallpaper.png stretch

See output configuration options in man 5 sway.

Swaybar configuration

Swaybar follows a very similar configuration to the i3bar. Simply, add a bar section to your config:

# swaybar
bar {


See also: Configuring i3bar and i3bar compatibility.

Taking screenshots

Read man swaygrab.


Insert any question to this FAQ

Update both sway and wlc and then try again. Look through known issues in sway. Look through known issues in wlc. Did you read the man pages? We ship detailed man pages, start with man sway. Read your config file, too. And read the log.

How do I get rid of title bars on applications?

Use the default_border command in your config. (This command used to be called new_window, but that command has been deprecated and will be removed in the future.) default_border normal shows title bars, whereas none and pixel do not. The border command operates on the currently focused window only. default_border is a setting, border is an action.

Where are my tray icons?

Swaybar currently only supports tray icons that implement the StatusNotifierItem (KDE) specification. The older SystemTray specification that uses Xembed is planned, but currently unsupported. If one still wants to use programs that implement the older spec, the KDE helper program xembedsniproxy can be used to translate between the two protocols. However, this program is buggy and we will not help you use it until xembed is fully supported.

How do I configure urxvt transparency?

urxvt transparency requires "real transparency" settings. Add this to your .Xresources and reload via xrdb ~/.Xresources:

URxvt*depth: 32
URxvt*background: rgba:0000/0000/0200/c800

Be aware that this configuration will conflict with the URxvt.reversevideo and if you enable the reversevideo option, the text will become transparent instead of the background.

I'm not using logind but still want DBus/PolKit/power management to work.

What can I do?

If you're using ConsoleKit2, launch sway using

exec ck-launch-session dbus-launch --sh-syntax --exit-with-session sway

Alternatively, you could omit the ck-launch-session part.


xbacklight is, of course, a tool for X. Instead, you can use brightnessctl, light or just directly manipulate /sys/class/backlight.

Which terminal emulator can I use?

You can use either X- or Wayland-native terminal emulator with little difference in terms of functionality.

termite (which is Wayland-native) is a popular recommendation, along with other VTE-based terminals like GNOME Terminal. X-based urxvt is another popular option.

Why am I getting Error on line XX […] Unknown key?

In your config, you should replace at line XX bindsym by bindcode.


How do I report issues?

We will expect three things from you: your sway version, your config file, and a debug log. Obtain your version like so:

swaymsg -t get_version

If this doesn't work, use:

sway -v

Obtain a debug log like so:

sway -d 2> ~/sway.log

This will record information about Sway's activity when it's running. Briefly reproduce your problem and exit sway. Upload this file, along with your config, to gist.github.com, and include this in a GitHub issue (or when asking for help on IRC). When preparing a debug log, make it brief - start up sway, do the minimum work necessary to reproduce the error, then close sway. Explain the steps you took in plain English in your GitHub issue as well.

I just installed sway. I can move my mouse cursor but my keyboard does not work.

Are you pressing keys that are bound to do anything? Read the config file. If $mod+Return is bound to exec urxvt (which it is by default) - do you have Urxvt installed? Try $mod+2 or $mod+8 - does it switch workspaces?

I can't run anything.

Check for keyboard shortcuts in the config file to start your launcher. Are you trying to run x applications? You probably don't have xwayland installed. Consult your distribution's documentation for instructions on installing xwayland.

My keyboard shortcuts does not work.

If you're running sway on top of X11, with i3 running, i3 will intercept any key presses that would otherwise be sent to sway. If you use the exact same key bindings then sway will never receive them.

i3-dmenu-desktop does not work.

There's a patch but it cannot be merged upstream. See issue #511 for more info.

You can still apply the patch manually though:

wget 'https://patch-diff.githubusercontent.com/raw/i3/i3/pull/2265.patch'
sudo patch -p0 /usr/bin/i3-dmenu-desktop < 2265.patch

rofi does not get focus on launch.

rofi has an issue in X which requires mouse to be moved over it to gain focus after launch. This is planned to be removed in Wayland port (see upstream discussion).

My favorite application isn't displayed right, how can I fix this?


Disabling client-side GTK3 decorations

Try one of the following:

  • Install a patched GTK3 which removes CSD by default (check out what your distro offers; AUR)
  • Patch the application to remove decorations. See gtk_window_set_decorated
  • Make an upstream pull-request, that makes decorations optional at runtime.
  • Use a CSS hack in ~/.config/gtk-3.0/gtk.css: .titlebar.default-decoration { margin: -200px; opacity: 0; } (this disables titlebars without extra buttons, like gnome terminal's, but not nautilus')

Disabling client-side Qt decorations

Qt currently defaults to using the X11 backend instead of its native Wayland backend. To use the Wayland backend, set QT_QPA_PLATFORM=wayland. Then Qt will also draw client-side decorations for all windows, to disable this, set QT_WAYLAND_DISABLE_WINDOWDECORATION="1"

Window rules to adjust sway's borders

If you want to use a particular application's built-in window decorations over the sway borders, you can write a rule like this in your config:

for_window [id="nautilus"] border none

Issues with Java applications

  • Try to set _JAVA_AWT_WM_NONREPARENTING=1 in your environment. Source

This seems to fix blank windows and menus that are drawn at a wrong offset to the selected menu item.

I run an Arch Linux based distribution without systemd. and sway does not start.

Use the hook files provided here.

I have a multi-gpu setup (like intel+nvidia or intel+amd) and sway does not start

Unless specified otherwise, wlc will choose a card for you and you could have a similar message in sway's log:

10/11/16 20:05:08 - [main.c:43] [wlc] Activating tty
10/11/16 20:05:08 - [main.c:41] [wlc] Connector 0 is not connected or has no modes
10/11/16 20:05:08 - [main.c:41] [wlc] Connector 1 is not connected or has no modes
10/11/16 20:05:08 - [main.c:43] [wlc] become active
10/11/16 20:05:08 - [main.c:43] [wlc] Cleanup wlc
10/11/16 20:05:08 - [handlers.c:911] Compositor is ready, executing cmds in queue
10/11/16 20:05:08 - [main.c:43] [wlc] Closing Xwayland
10/11/16 20:05:08 - [main.c:43] [wlc] Closed drm
10/11/16 20:05:08 - [main.c:43] [wlc] Restoring vt 1 (0x4) (fd 0)

Try with a different default card (listed in /dev/dri/), for example:

WLC_DRM_DEVICE=card1 sway

It's likely that you want sway to use the integrated (Intel) card, because probably that's the only one directly connected to the laptop monitor. However, the mapping between node names in /dev/dri/ and actual cards isn't guaranteed to be the same across reboots. This script detects which is the device path of the integrated card and launches sway accordingly:

#! /bin/bash

val=$(udevadm info -a -n /dev/dri/card1 | grep boot_vga | rev | cut -c 2)
cmd="WLC_DRM_DEVICE=card$val sway"
eval "$cmd"

Can I use Sway with Gnome?

In the X11 world the window manager and desktop environment could be mix and matched. In Wayland it's not as easy to mix different window managers and desktop environments. While some people could use the i3 window manager with the gnome desktop, this is not possible with sway.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.