Scott Anderson edited this page Dec 6, 2018 · 149 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, and others don't. If you have issues starting sway and you use a login manager, your first step should be disabling the login manager and running sway as described by man 1 sway. If it works, report the bug to your login manager, not to sway.

You can start sway automatically without a login manager, for example, by adding this to your .bashrc:

# If running from 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 the default config - it has comments that explain what each option does. Read man 5 sway for more information about each config command.

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

For more details read man 5 sway and search for output.


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.

Fractional scaling

Fractional scaling is supported but is not recommended. Your display does not have fractional pixels - and if you enable fractional scaling we cannot display your windows faithfully, and your image quality will be degraded. You should instead choose the integer scale factor appropriate for your display and configure your software's font size as necessary. If you still want to use fractional scaling, it is as simple as e.g. output <name> scale 1.5.

Display rotation

output <name> transform 90 will rotate output <name> by 90 degrees clockwise. Read man 5 sway and search for transform to see other options, like flipping across an axis.

Input configuration

A list of input devices is available by running swaymsg -t get_inputs. Use the identifier for the device you want to configure in your config file:

input <identifier> {
    # ...config options...

See man 5 sway-input for a summary of the available options.

Keyboard layout

input <identifier> {
    xkb_layout us,de
    xkb_variant ,nodeadkeys
    xkb_options grp:alt_shift_toggle

See man 7 xkeyboard-config for options you can use with the xkb_layout, xkb_model, xkb_options, xkb_rules, and xkb_variant commands.


  • Make caps lock work as escape: xkb_options caps:escape
  • Swap escape and caps lock: xkb_options caps:swapescape
  • Make caps lock work as control: xkb_options ctrl:nocaps

Keyboard repeat delay and rate

input <identifier> {
    repeat_delay 500
    repeat_rate 5

Libinput config options

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

See man 5 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 supports most of the same features as i3bar, and is configured in the same way. Add a bar section to your config:

bar {
    # options..

For the full list of options, see man 5 sway-bar.

Taking screenshots

X11 tools like scrot are not supported. Try grim.


Before asking questions...

Update both sway and wlroots and then try again. Look through known issues in sway and known issues in wlroots. Did you read the 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. 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 does not currently support tray icons.

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.

You may wish to add exec xrdb ~/.Xresources to your sway config to configure this on startup.

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, as the name would imply, 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, 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.

If the problem isn't immediately obvious, you will likely be required to debug it yourself - we are volunteers and only have so much free time.

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 ''
sudo patch -p0 /usr/bin/i3-dmenu-desktop < 2265.patch

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

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 Linux distribution without systemd and sway does not start.

See here.

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

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

To use a different default card (listed in /dev/dri/), set this environment variable before starting sway:

WLR_DRM_DEVICES=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:

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

You can also configure multiple graphics cards like so:

WLR_DRM_DEVICES=card0:card1 sway

The first card is used for actual rendering, and display buffers are copied to the secondary cards for any displays connected to them.

My GTK+3 theme isn't working

See GTK 3 settings on Wayland.

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.