Skip to content
Jakub Fišer edited this page Apr 7, 2022 · 287 revisions
Clone this wiki locally

ConfigurationFAQTroubleshooting

This wiki is not maintained by the Sway developers, it's user-contributed. Feel free to edit it. Please discuss on IRC with the rest of the users before making big intrusive changes.

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 can be used instead. 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
[ "$(tty)" = "/dev/tty1" ] && exec sway

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

# If running from tty1 start sway
set TTY1 (tty)
[ "$TTY1" = "/dev/tty1" ] && exec sway

Configuration

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.

Multihead

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>

or

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

However, when reloading sway while using clamshell mode, the displays may reset (i.e. both displays will be enabled). To stop this, save this bash script:

#!/usr/bin/bash
if grep -q open /proc/acpi/button/lid/LID/state; then
    swaymsg output <LAPTOP> enable
else
    swaymsg output <LAPTOP> disable
fi

Replace <LAPTOP> with the name of the display.

To make sure this script runs whenever Sway is reloaded, add this line to your sway config:

exec_always /path/to/script.sh

HiDPI

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. On Arch Linux, it is available as an official package.

Another alternative is wlsunset, which is more lightweight.

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

Nothing prevents having multiple configurations for different specific devices:

# default layout
input "1:1:AT_Translated_Set_2_keyboard" {
   xkb_layout us
}

# custom layout for an external keyboard
input "1452:591:Custom_Keyboard" {
   xkb_layout YourCustomLayout
}

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.

User-specific settings such as symbols will be loaded from their respective directories in ~/.xkb/ or $XDG_CONFIG_HOME/xkb/.

Examples:

  • 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

Note that to trigger several options, you need to list them separated with a comma, e.g. xkb_options caps:escape,altwin:swap_lalt_lwin; if you instead write several xkb_options-lines, only the last one will take effect.

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
}

Load a modified custom xkb keymap (xmodmap equivalent)

See #4250

If you just want to change a couple of keymappings, you can create your own by overriding the keymappings of your usual layout.

input type:keyboard {

  # Modified programmer Dvorak. File at ~/.xkb/symbols/dvp_alt_gr_remapped_to_super
  xkb_layout "dvp_alt_gr_remapped_to_super"

  # Capslock key should work as escape key
  # See /usr/share/X11/xkb/rules/xorg.lst for options
  xkb_options caps:escape

  repeat_delay 250
  repeat_rate 45
}

The entirety of ~/.xkb/symbols/dvp_alt_gr_remapped_to_super:

default partial alphanumeric_keys
xkb_symbols "basic" {
        include "us(dvp)"
        name[Group1] = "Modified programmer Dvorak";
        key <RALT> { [ Super_L, Super_R ] };
};

The full documentation on how to override keymappings is available at this link. Here a slightly digested version with a practical commented example.

Libinput config options

input <device name> {
    left_handed enabled
    tap enabled
    natural_scroll disabled
    dwt enabled
    accel_profile "flat" # disable mouse acceleration (enabled by default; to set it manually, use "adaptive" instead of "flat")
    pointer_accel 0.5 # set mouse sensitivity (between -1 and 1)
}

See man 5 sway-input for all available options.

Wallpapers

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.

Also, see https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway for more ideas.

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 {
    # ...bar options..
}

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

Taking screenshots

X11 tools like scrot do not work. Try grim.

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

shotman is a simple, light, modern UI for screenshooting, and also relies on the former.

flameshot has a simple and inituitive GUI with various editing tools.

swappy is another tool (written in C, uses GTK and Pango) that pops up a GUI and allows basic operations on the screenshot such as adding text, arrows, circles, squares and choosing colors. Has a config file to customize the GUI. Can also work without grim.

Also, see https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway for more ideas.

Creating screencasts

Try wf-recorder for screen recording of wlroots-based compositors like swaywm. If you use OBS Studio, versions newer than 27.0 natively support screen recording using pipewire. For older versions you can use wlrobs recording plugin for wlroots-based compositors.

Also, see https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway for more ideas.

Program launchers

  • bemenu works as a dmenu replacement.
  • sway-desktop-launcher: TUI Application launcher with Desktop Entry support.
  • wofi is a rofi-like launcher.
  • yofi is a minimalistic menu for wayland.

Also, see https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway for more ideas.

Screen zooming feature

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

Setting Environmental Variables

How you set variables will depend on how sway was started.

Environment variables are inherited from the process that starts sway. You need to set variables there.

Some of the possible options are:

  • login manager: check the documentation.
  • login shell: export them there before launching sway.
  • user service: use the EnvironmentFile= key and an environment file.

More details here.

FAQ

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.

Note that default_border only affects new windows. Even after reloading sway, you will need to close and re-open any windows you do not wish to see the title bar on.

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

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.

For instance:

bindsym --locked XF86MonBrightnessDown exec brightnessctl set 5%-
bindsym --locked XF86MonBrightnessUp exec brightnessctl set 5%+

Which terminal emulator can I use?

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

Alacritty, Kitty, or foot will use Wayland without additional configuration. You can use 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.

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
}

Memorize and switch target windows

Configuration example:

##################################
# window switch setting
set $mode_set_switch_window "set_switch_window: [0]-[9]"
mode $mode_set_switch_window {
    bindsym 1 mark 1; mode "default"
    bindsym 2 mark 2; mode "default"
    bindsym 3 mark 3; mode "default"
    bindsym 4 mark 4; mode "default"
    bindsym 5 mark 5; mode "default"
    bindsym 6 mark 6; mode "default"
    bindsym 7 mark 7; mode "default"
    bindsym 8 mark 8; mode "default"
    bindsym 9 mark 9; mode "default"
    bindsym 0 mark 0; mode "default"
    bindsym Return mode "default"
    bindsym Escape mode "default"
}
bindsym $mod+ctrl+t mode $mode_set_switch_window
set $mode_switch_window "switch_window: [0]-[9]"
mode $mode_switch_window {
    bindsym 1 [con_mark="1"] focus; mode "default"
    bindsym 2 [con_mark="2"] focus; mode "default"
    bindsym 3 [con_mark="3"] focus; mode "default"
    bindsym 4 [con_mark="4"] focus; mode "default"
    bindsym 5 [con_mark="5"] focus; mode "default"
    bindsym 6 [con_mark="6"] focus; mode "default"
    bindsym 7 [con_mark="7"] focus; mode "default"
    bindsym 8 [con_mark="8"] focus; mode "default"
    bindsym 9 [con_mark="9"] focus; mode "default"
    bindsym 0 [con_mark="0"] focus; mode "default"
    bindsym t mode $mode_set_switch_window
    bindsym Return mode "default"
    bindsym Escape mode "default"
}
bindsym $mod+t mode $mode_switch_window

Move workspace to current output when switching

If you want your workspace to me moved to the current output when you switch to it using $mod+<number> instead of you being refocused to a different output where the workspace is currently bound, replace your bindsym $mod+<number> lines in your configuration with this (for each <number> of course):

bindsym $mod+1 [workspace="1"] move workspace to output current; workspace number 1

Troubleshooting

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.

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 'https://patch-diff.githubusercontent.com/raw/i3/i3/pull/2265.patch'
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). You can achieve this by appending the following snippet to your ~/.profile file:
if [ "$XDG_SESSION_DESKTOP" = "sway" ] ; then
    # https://github.com/swaywm/sway/issues/595
    export _JAVA_AWT_WM_NONREPARENTING=1
fi

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/studio.sh

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 https://wiki.archlinux.org/index.php/NetworkManager#Appindicator

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:

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

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 wlroots issue #1119. This is an Xwayland bug fixed in 1.20.9.

Workaround:

  1. If it does not exist, create the file ~/.Xresources

  2. Add the following line to ~/.Xresources:

    Xft.dpi: 96
    
  3. 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 : https://gitlab.freedesktop.org/xorg/xserver/issues/899

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: https://mastransky.wordpress.com/2020/03/16/wayland-x11-how-to-run-firefox-in-mixed-environment/

Android studio draws the menus in the wrong place

Try something like this:

# For Android Studio
export _JAVA_AWT_WM_NONREPARENTING=1
export STUDIO_JDK=/usr/lib/jvm/java-14-openjdk

# For Gradle
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk

Adjust the paths so that they point to a valid location on your system.

GTK+ applications take 20 seconds to start

This is due to GTK+ waiting for xdg-desktop-portal to start via D-Bus. This times out because the D-Bus activated service doesn't know what WAYLAND_DISPLAY to connect to.

This can be fixed by adding the following to your configuration file:

exec dbus-update-activation-environment --systemd DISPLAY WAYLAND_DISPLAY SWAYSOCK

Alternatively, set GTK_USE_PORTAL=0 in your environment.

More details: https://github.com/swaywm/sway/issues/5732

Wayland won't let me run apps as root

Generally speaking, running graphical applications as root is discouraged. Modern Linux distributions usually ship with a configured Polkit system which allows applications to request permissions for specific administrative actions as needed. Arch Linux wiki about Polkit is a good source of information https://wiki.archlinux.org/title/Polkit.

As a Sway user, all you probably need to do is run any one of the polkit auth agents. When a polkit auth agent is running you will get a prompt when an application supports Polkit and needs administrative permissions for some actions.

Auth agent exact location (and whether they are installed) depend on your distribution. Two most common agents are:

  • polkit-gnome-authentication-agent-1 (GTK/Gnome)
  • polkit-kde-authentication-agent-1 (QT/KDE)

They usually reside in /usr/libexec or /usr/lib directories. You will want to put for example following in your sway config: exec "/usr/libexec/polkit-gnome-authentication-agent-1"

If the application does not support Polkit or you are running system without Polkit there is an additional fallback option if you really need to run a gui application as root: sudo --preserve-env=XDG_RUNTIME_DIR,WAYLAND_DISPLAY <app> or simply sudo -E <app>. This should be a last-resort option however.

Clutter applications hang at startup

This is ultimately caused by Clutter's reliance on the deprecated wl_shell protocol. Unless/until https://gitlab.gnome.org/GNOME/clutter/-/merge_requests/5 is merged, a workaround is to set CLUTTER_BACKEND=gdk to have it use gdk rather than attempt to interface directly with the compositor.

Sway 1.6 shows garbage or a blank screen on Nouveau

Could manifest as a blank screen where windows or bars are not drawn at all, only the mouse pointer. Could manifest an inactive display where the monitor receives no input at all.

Try setting WLR_DRM_NO_MODIFIERS=1. If you have it set, try un-setting it.

Issues when modifiers are enabled are due to two Nouveau bugs, fixed in these merge requests, and released in mesa 21.1.0:

How can I setup keyboard volume keys?

You'll need to bind these keys in your configuration file. For instance, if you're using PulseAudio:

bindsym --locked XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle
bindsym --locked XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym --locked XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym --locked XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle