Sway - ArchWiki

# Sway

From ArchWiki
Jump to navigation Jump to search

Related articles

- Window manager

sway is a compositor for Wayland designed to be fully compatible with i3. According to the official website:

  Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

## Installation

sway can be installed with the sway package. The development version can be installed using wlroots-gitAUR and sway-gitAUR. It's advisable to always update wlroots when you update sway, due to tight dependencies.

You may also install swaylock and swayidle to lock your screen and set up an idle manager.

The default application launcher is dmenu and the default terminal emulator is alacritty. Before starting sway it is advisable to either install them or set a new launcher and terminal in the configuration.

## Starting

### Manually

To start Sway, simply type `sway` in the Linux console.

### From a display manager

Note: Sway does not support display managers officially.[1]

The sway session is located at `/usr/share/wayland-sessions/sway.desktop`. It is automatically recognized by modern display managers like GDM and SDDM.

It is also possible to start sway as a systemd user service through the display manager.

Also you can use text-based session manager, see Display manager#Console.

## Configuration

If you already use i3, then copy your i3 configuration to `~/.config/sway/config` and it should work out of the box. Otherwise, copy the sample configuration file to `~/.config/sway/config`. It is located at `/etc/sway/config`, unless the `DFALLBACK_CONFIG_DIR` flag has been set. See sway(5) for information on the configuration.

### Keymap

By default, sway starts with the US QWERTY keymap. To configure per-input:

    ~/.config/sway/config

    input * {
        xkb_layout "us,de,ru"
        xkb_variant "colemak,,typewriter"
        xkb_options "grp:win_space_toggle"
    }

    input <identifier> xkb_model "pc101"

More details are available in xkeyboard-config(7) and sway-input(5).

The keymap can also be configured using environment variables (`XKB_DEFAULT_LAYOUT`, `XKB_DEFAULT_VARIANT`, etc.) when starting `sway` with config options taking precedence over environment variables.

### Typematic delay and rate

For change typematic delay and rate you can add following lines to your `input` section:

    ~/.config/sway/config

    input <identifier> repeat_delay 300
    input <identifier> repeat_rate 30

### Statusbar

`sway` ships with a default status bar in the form of `swaybar` which runs in a pure Wayland environment. Installing the program i3status is an option to obtain a practical, default status bar under XWayland. All one has to do is add following snippet at the end of your sway config:

    ~/.config/sway/config

    bar {
        status_command i3status
    }

If you want to achieve colored output of i3status, you can adjust following part in the i3status configuration:

    ~/.config/i3status/config

    general {
        colors = true
        interval = 5
    }

In both examples, the system-wide installed configuration files has been copied over to the user directory and then modified.

Tip: waybar is an alternative to the bar included with sway (swaybar).

### Wallpaper

Since release 1.1.1 the wallpaper part of the SwayWM project was moved to swaybg, which is needed in order to run the output command.

This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name `"*"`):

    ~/.config/sway/config

    output "*" bg /home/onny/pictures/fredwang_norway.jpg fill

Of course you have to replace the file name and path according to your wallpaper.

You may use azoteAUR as the GTK3 frontend to swaybg.

Solid colors may be set as follows:

    output * bg #000000 solid_color

### Input devices

Its possible to tweak specific input device configurations. For example to enable tap-to-click and natural scolling for a touchpad, add an input block:

    ~/.config/sway/config

    input "2:14:ETPS/2_Elantech_Touchpad" {
        tap enabled
        natural_scroll enabled
    }

Where as the device identifier can be queried with:

    $ swaymsg -t get_inputs

The output from the command, sometimes has a "\" to escape symbols like "/" (ie `"2:14:ETPS\/2_Elantech_Touchpad"`) and it needs to be removed.

More documentation and options like acceleration profiles can be found in sway-input(5).

### HiDPI

Set your displays scale factor with the `output` command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.

    output <name> scale <factor>

You can find your display name with the following command:

    $ swaymsg -t get_outputs

### Custom keybindings

Special keys on your keyboard can be used to execute commands, for example to control your volume, your monitor brightness or your media player:

    ~/.config/sway/config

    bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
    bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
    bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle
    bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle
    bindsym XF86MonBrightnessDown exec brightnessctl set 5%-
    bindsym XF86MonBrightnessUp exec brightnessctl set +5%
    bindsym XF86AudioPlay exec playerctl play-pause
    bindsym XF86AudioNext exec playerctl next
    bindsym XF86AudioPrev exec playerctl previous

To allow a keybinding to be executed while the lockscreen is active add the `--locked` parameter to bindsym.

    bindsym --locked XF86AudioPlay exec playerctl play-pause

To control brightness you can use brightnessctl or light. For a list of utilities to control brightness and color correction see Backlight.

### Floating windows

To enable floating windows or window assignments, open the application and then use the `app_id`, the `class`, the `instance` and the `title` attributes to enable floating windows/window assignments. The following command will list the properties of all the open windows.

    $ swaymsg -t get_tree

To get only the `app_id`'s of all open windows use:

    $ swaymsg -t get_tree | grep "app_id"

To get the `app_id` of the focused window use:

    $ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'

If the `app_id` happens to be null for some windows, you might have to use the `class` and/or the `instance` attributes to enable floating mode/window assignments. You can search the output and create fine grained rules for your windows.

    ~/.config/sway/config

    for_window [app_id="galculator"] floating enable
    assign [class="firefox"] -> 3
    assign [class="^Urxvt$" instance="^htop$"] -> 9

This is similar to using xorg-xprop to find the `class` or `wm_name` attributes in X11.

### Xresources

Copy `~/.Xresources` to `~/.Xdefaults` to use them in Sway.

### Xwayland

If a program crashes on start with the error message "cannot open display," it is likely that the program you are using is an X11 program. In order to use the Xwayland compatibility layer to run X11 programs under Wayland, it is necessary to install the xorg-server-xwayland package.

If you would like to disable Xwayland entirely and run a "pure" Wayland session, uninstall the xorg-server-xwayland package and set the following configuration option:

    ~/.config/sway/config

    xwayland disable

Note: Some programs need special environment variables or configuration options to run natively under Wayland, and other programs (including most proprietary applications) do not support Wayland at all. Currently it is recommended to keep Xwayland on so that legacy applications can be used.

## Tips and tricks

### Autostart on login

To start sway from tty1 on login with default US keyboard, edit:

    ~/.bash_profile

    if [[ -z $DISPLAY ]] && [[ $(tty) = /dev/tty1 ]]; then
      XKB_DEFAULT_LAYOUT=us exec sway
    fi

### Enable CapsLock/NumLock

Enable the capslock and/or numlock by adding the following lines to your sway config

    ~/.config/sway/config

    input * xkb_capslock enable
    input * xkb_numlock enable

### Current keyboard layout

The current keyboard layout can be retrieved as follows, where `kbd_identifier` needs to be replaced with your keyboard's identifier:

    $ swaymsg -t get_inputs | jq '.[] | select(.identifier == "kbd_identifier") | .xkb_active_layout_name' | tr -d '"'

### Backlight toggle

To turn off (and on) your displays with a key (e.g. `Pause`) bind the following script in your Sway `config`:

    #!/bin/sh
    read lcd < /tmp/lcd
        if [ "$lcd" -eq "0" ]; then
            swaymsg "output * dpms on"
            echo 1 > /tmp/lcd
        else
            swaymsg "output * dpms off"
            echo 0 > /tmp/lcd
        fi

### Screen capture and screen sharing

See Screen capture#Wayland.

### Control swaynag with the keyboard

Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as swaynagmodeAUR may be used to enable interaction via keyboard shortcuts.

Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as `swaynagmode --select right` or `swaynagmode --confirm`.

Swaynagmode by default triggers the sway mode `nag` upon initialization, followed by `default` on exit. This makes it easy to define keybindings in your sway configuration:

    ~/.config/sway/config

    set $nag exec swaynagmode
    mode "nag" {
      bindsym {
        Ctrl+d    mode "default"

        Ctrl+c    $nag --exit
        q         $nag --exit
        Escape    $nag --exit

        Return    $nag --confirm

        Tab       $nag --select prev
        Shift+Tab $nag --select next

        Left      $nag --select next
        Right     $nag --select prev

        Up        $nag --select next
        Down      $nag --select prev
      }
    }

Note that, beginning in sway version 1.2, mode names are case-sensitive.

You can configure sway to use swaynagmode with the configuration command `swaynag_command swaynagmode`.

### Change cursor theme and size

To set the cursor theme and size:

    ~/.config/sway/config

    seat seat0 xcursor_theme my_cursor_theme my_cursor_size

Where `my_cursor_theme` can be set to or replaced by a specific value like `default`, `Adwaita` or `Simple-and-Soft`, and `my_cursor_size` a value like `48`.

You can inspect their values with `echo $XCURSOR_SIZE` and `echo $XCURSOR_THEME`.

Note that you need to restart the application to see the changes.

Note: Wayland uses client-side cursors. It's possible that applications do not evaluate the values of `$XCURSOR_SIZE` and `$XCURSOR_THEME`.

## Troubleshooting

### Application launchers

i3-dmenu-desktop, dmenu, and rofi all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running `pkill` does too.

bemenu is a native Wayland dmenu replacement which can optionally be combined with j4-dmenu-desktopAUR to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):

    j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'

You may need to set `BEMENU_BACKEND` environment variable to "wayland" if you choose not to disable XWayland.

You can also build your own with a floating terminal and fzf as discussed in a GitHub issue.

Also `krunner` binary provided by plasma-workspace package can serve as launcher, offering both XWayland and native Wayland support.

wofi-hgAUR is a command launcher, that provides the same features as rofi but running under wayland. It is based on wlroots library and use GTK3 for rendering. It works pretty well with sway.

### Virtualization

Sway works with both VirtualBox and VMware ESXi.

#### Unable to start Sway from tty

For ESXi, you need to enable 3D support under the Hardware Configuration > Video card settings. See also VMware#Enable 3D graphics on Intel and Optimus.

#### No visible cursor

When using the VMSVGA graphics controller, the cursor is invisible. This can be fixed by using software cursors as discussed in [2]:

    $ export WLR_NO_HARDWARE_CURSORS=1

### Sway socket not detected

Using a `swaymsg` argument, such as `swaymsg -t get_outputs`, will sometimes return the message:

    sway socket not detected.
    ERROR: Unable to connect to

when run inside a terminal multiplexer (such as gnu screen or tmux). This means `swaymsg` could not connect to the socket provided in your `SWAYSOCK`.

To view what the current value of `SWAYSOCK` is, type:

    $ env | fgrep SWAYSOCK
    SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock

To work around this problem, you may try attaching to a socket based on the running sway process:

    $ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock

To avoid this error, run the command outside of a multiplexer.

### Unable to retrieve socket path

Requesting messages from `swaymsg -t` on a tty may return the following message:

    Unable to retrieve socket path

`SWAYSOCK` environment variable is set after launching Sway, therefore a workaround to this error is to request `swaymsg -t [message]` in a terminal inside Sway.

### Keybindings and keyboard layouts

By default, if you are using more than one keyboard layout, e.g. `input * xkb_layout "us,ru"`, bindings may become broken when you switch on some secondary layout.

Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add `--to-code` key to sensitive `bindsym` lines like this:

    bindsym --to-code {
      $mod+$left focus left
      $mod+$down focus down
      $mod+$up focus up
      $mod+$right focus right
    }

### Java applications

Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the `_JAVA_AWT_WM_NONREPARENTING` environment variable set to 1.

If you start the application from a launcher like rofi or dmenu, you might want to modify the application desktop entry as shown in Desktop entries#Modify environment variables.

### Scroll on border

If using the mouse scroll wheel on an application's border crashes sway, you could use `border none` for the `app_id` (e.g. Firefox).

## See also

- GitHub project
- Sway official wiki
- sr.ht git page
- Website
- Announcing the release of sway 1.0

Categories:

- Tiling WMs
- Dynamic WMs