Skip to content
Ivan Jager edited this page Jul 29, 2020 · 225 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 driver is required instead. 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 .bash_profile (.zlogin or .zprofile for Zsh):

# If running from tty1 start sway
if [ "$(tty)" = "/dev/tty1" ]; then
	exec sway

For Fish, create the file ~/.config/fish/conf.d/

# If running from tty1 start sway
set TTY1 (tty)
if test -z "$DISPLAY"; and test $TTY1 = "/dev/tty1"
  exec sway


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-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 your config file:

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

Take a note that you might want to change the focus of monitor on sway launch. Add this to your sway config:

focus output <name-or-identifier>


exec swaymsg focus output <name-or-identifier>

so it doesn't trigger on reload.

For more details read man 5 sway-output.

Clamshell Mode

AKA Closed Display mode. This mode is where your laptop lid is closed and you have external monitor(s) as outputs. As of Sway 1.1 you can use switch events to drive certain functionality, such as disabling an output upon a laptop lid being closed. Pass your laptop output name into the following, which can by found with: swaymsg -t get_outputs for example eDP-1.

set $laptop <laptop_output_identifier>
bindswitch --reload --locked lid:on output $laptop disable
bindswitch --reload --locked lid:off output $laptop enable


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-output and search for transform to see other options, like flipping across an axis.

For automatic display rotation via a built-in accelerometer, see rot8.

Redshift equivalent

Redshift adjusts the color temperature of your screen according to your surroundings. This may help your eyes hurt less if you are working in front of the screen at night. Unfortunately, Redshift does not support Wayland.

However, there is a fork of Redshift called gammastep which does have Wayland support.

It has not yet been packaged for any major distribution, but there is an AUR package for Arch Linux.

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 "type:keyboard" {           # or 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. Separate multiple options with commas.


  • 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
  • Swap left alt and super, and set caps lock to escape: xkb_options altwin:swap_lalt_lwin,caps:escape

Load custom xkb keymap file (since #3999)

input "type:keyboard" {           # or input <identifier> 
    xkb_file ~/.config/xkb/custom

Keyboard repeat delay and rate

input "type:keyboard" {           # or input <identifier> 
    repeat_delay 500
    repeat_rate 5

xmodmap equivalent

See #4250

Libinput config options

input <device name> {
    left_handed enabled
    tap enabled
    natural_scroll disabled
    dwt enabled
    pointer_accel 0.5 # set mouse sensitivity (between -1 and 1)

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

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.

Grimshot provides a simpler interface if you're looking for something more high level (and relies on grim and slurp internally).

Creating screencasts

Try wf-recorder for screen recording of wlroots-based compositors like swaywm. If you use OBS Studio, wlrobs is a plugin for wlroots-based compositors.

Program launchers

Try wofi for a rofi-like experience or bemenu as a dmenu replacement.

Screen zooming feature

Not yet possible with swaywm/wlroots. Please look / get involved here.


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?

Initial tray icon support for swaybar was merged with #3249 pull request. Missing features are tracked in #3799.

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, brillo, 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. Alacritty and Kitty will use Wayland without additional configuration. 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.

Locale-specific configuration tricks

Workspace switching on the French layout

Because French number keys only produce numbers when Shift is pressed (or Caps Lock is active), you'll need to setup key bindings with the various special characters under the numbers (&, é, ", etc):

bindsym $mod+ampersand workspace 1
bindsym $mod+eacute workspace 2
bindsym $mod+quotedbl workspace 3
bindsym $mod+apostrophe workspace 4
bindsym $mod+parenleft workspace 5
bindsym $mod+minus workspace 6	# +section on Apple keyboards
bindsym $mod+egrave workspace 7
bindsym $mod+underscore workspace 8	# +exclam on Apple keyboards
bindsym $mod+ccedilla workspace 9
bindsym $mod+agrave workspace 10

Key bindings on a dual US/Russian layout

If you have configured your keyboard with a US and a Russian layout (input * xkb_layout us,ru), your bindings using Latin script letters won't work when the Russian keyboard is active (for instance, $mod+f won't work, because you can't produce the letter f with the Russian layout).

To make key bindings work regardless of the currently active layout, you can use bindsym --to-code:

bindsym --to-code {
    $mod+b splith
    $mod+v splitv


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 alacritty (which it is by default) - do you have alacritty 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 do 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 [app_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.

Issues with JetBrains IDE popups/menus losing focus

Some JetBrains IDEs (including Android Studio) ship with a Java 1.8 JRE, but there are fixes included in later JRE versions that are necessary to run properly in Sway. You can instruct your IDE to use a different JRE through an invocation of the form:

$ STUDIO_JDK=/usr/lib/jvm/java-11-openjdk-amd64/ /opt/android-studio/bin/

If you are running Sway 1.4 or earlier, you will also need to upgrade to Sway/wlroots master, as there are necessary fixes there too.

Status icon doesn't show up

There are two standards for status icons: XEmbed and StatusNotifierItem (SNI). XEmbed is legacy and unimplemented in Sway. SNI is supported by swaybar. If your app uses XEmbed, the status icon won't show up. You should ask them to upgrade to SNI.

For network-manager-applet, see

I run a 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=/dev/dri/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=/dev/dri/card$val sway"
eval "$cmd"

You can also configure multiple graphics cards like so:

WLR_DRM_DEVICES=/dev/dri/card0:/dev/dri/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.

After unplugging an external display, some applications appear too large on my HiDPI screen

See Issue 1119.

  1. If it does not exist, create the file
  1. Add the following line to ~/.Xresources:
Xft.dpi: 96
  1. Add the following line to the sway config:
exec xrdb -load ~/.Xresources

Is an application using Xwayland?

To figure out whether an application uses Xwayland or native Wayland, you can try one of these solutions:

  1. Run xeyes and move the mouse over the app. The eyes will only move if the window is using Xwayland.
  2. Add for_window [shell=".*"] title_format "%title :: %shell" to your config file.
  3. swaymsg -t get_tree dumps information about all windows.

Mouse events (clicking, scrolling) aren't working on some of my workspaces

If your monitor layouts uses negative pixels, you're probably hitting this issue :

This is a Xwayland bug. The workaround is to rearrange your workspaces to not use negative pixels.

Xwayland DPI increases after hotplug

This is an Xwayland bug. This usually results in oversized text. As a workaround, add Xft.dpi: 96 to ~/.Xresources and add exec xrdb -load ~/.Xresources to your Sway config.

I can't open links in external applications in Firefox

If you get the message "Firefox is already running", set the environmental variable MOZ_DBUS_REMOTE=1 (Firefox 74+, dbus required). See explanation here:

You can’t perform that action at this time.