Skip to content
Get packs

Guide · Open source

How to use sway: install, configure and run it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Sway is a tiling window manager for Linux that runs on Wayland, the newer display system that has been replacing X11. It is compatible with i3, so if you already use i3 you can usually reuse your config file. This guide covers installing sway, setting up its configuration file, and starting it.

swayswaywm/sway · ★ 17.5k · MIT

Quick start

  1. 1Install dependencies. Install the packages listed in the README, or use the sway package from your distribution.
  2. 2Build from source (optional). Run meson setup build/, then ninja -C build/, then sudo ninja -C build/ install.
  3. 3Create the config folder. Make ~/.config/sway if it does not exist.
  4. 4Copy a config file. Copy your i3 config to ~/.config/sway/config, or copy the sample config from /etc/sway/config.
  5. 5Read the manual. Run man 5 sway to learn the configuration options.
  6. 6Start sway. Run sway from a TTY or choose sway at your display manager login.

What sway is and who it suits

Sway is a window manager, not a full desktop environment. It arranges your windows automatically in tiles, and you control it mainly from the keyboard. It needs other tools for things like panels and wallpapers.

  • Good fit: Linux users who already use i3 and want Wayland, or who prefer keyboard-driven tiling layouts.
  • Good fit: users comfortable editing a text config file, and developers testing Wayland desktop setups.
  • Not a fit: people who want a complete desktop out of the box, or who want point-and-click setup.
  • The project describes sway as a Linux Wayland compositor, so it is not aimed at macOS or Windows.

Install sway from your package manager or source

The simplest route is the sway package for your distribution. The README says sway is available in many distributions, so search your package manager for "sway".

To build from source, install the dependencies listed in the README: meson, wlroots, wayland, wayland-protocols, pcre2, json-c, pango and cairo. gdk-pixbuf2 is optional and adds image formats for the system tray. swaybg is optional and provides wallpaper. scdoc is optional and builds man pages. git is optional and adds version info.

Then run the three build commands from the README. The final install step uses sudo.

  • meson, wayland-protocols, scdoc and git are compile-time dependencies.
  • For building the latest HEAD of sway and wlroots for testing or development, the README points to the project's Development Setup wiki page.
meson setup build/ ninja -C build/ sudo ninja -C build/ install

Set up your configuration file

If you already use i3, copy your i3 config to ~/.config/sway/config and it should work out of the box. Otherwise, copy the sample configuration file to ~/.config/sway/config. The README says the sample is usually located at /etc/sway/config.

For details on configuration options, the README says to run the sway manual page for section 5.

  • Config file path: ~/.config/sway/config
  • Sample config is usually at /etc/sway/config
  • Configuration reference: man 5 sway
man 5 sway

Start sway

Sway is started from a TTY or from a display manager, which is the login screen. Once it starts, it manages your windows automatically according to your configuration.

  • From a TTY: run sway.
  • From a display manager: select sway as the session at login.
sway

Where to get help

The README links to a sway wiki as the FAQ, and to an IRC channel, #sway on irc.libera.chat, for questions. Releases are signed with the key E88F5E48 and published on GitHub.

What people use it for

  • Moving an existing i3 setup to Wayland by reusing the i3 config file.
  • Running a keyboard-driven tiling layout on a Linux laptop or desktop.
  • Testing Wayland desktop setups as a developer.
  • Building sway and wlroots from source for development work.

Frequently asked questions

Is sway free?

Sway is open source under the MIT licence, and its source code is in the swaywm/sway repository. The README does not list any price.

Can I use my i3 config with sway?

Yes. The README says that if you already use i3, you can copy your i3 config to ~/.config/sway/config and it will work out of the box.

Does sway run on macOS or Windows?

The README describes sway only as a Linux Wayland compositor, so it is not presented as a macOS or Windows option.

What do I need to build sway?

The README lists meson, wlroots, wayland, wayland-protocols, pcre2, json-c, pango and cairo as dependencies. It also lists optional packages such as swaybg for wallpaper and scdoc for man pages.

How do I start sway?

Run sway from a TTY or pick it from a display manager at login. Sway then arranges your windows automatically.

What are the alternatives to sway?

The project lists i3, Hyprland, river and Wayfire as comparable projects. i3 is the X11 option that sway is compatible with, while the others are also Wayland window managers.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Sway suits Linux users who already know i3 or want a keyboard-driven tiling window manager on Wayland, and who are comfortable editing a text config file. If you want a full desktop environment, a point-and-click setup, or macOS or Windows support, pick something else.

Install options & downloads