Sway: the i3-compatible Wayland compositor, and what it costs to switch

What Sway actually replaces, and for whom

Sway is a Wayland compositor that presents the same window management model as i3. On X11, the window manager and the display server are separate programs, and i3 is the former. On Wayland the compositor is the display server, so Sway occupies both roles at once. That is the whole reason the project exists: it gives people who already think in i3's terms a Wayland session without asking them to learn a different window management paradigm.

The audience is narrow and well defined. If you have a working i3 configuration with workspaces, containers, tabbed and stacked layouts, and keyboard-driven focus movement, Sway is aimed at you. The README states that copying an i3 config to `~/.config/sway/config` will "work out of the box." That claim is the project's central promise, and it is also the claim most likely to be tested in the first ten minutes of use.

It is not a desktop environment. There is no settings panel, no file manager, no notification daemon in the core repository. The top-level entries show the scope: a compositor, a bar (`swaybar/`), a notification program (`swaynag/`), and a control client (`swaymsg/`). Anything beyond that is somebody else's package.

How the compositor, bar and control socket fit together

The repository is organised as one compositor plus small satellite binaries. `sway/` holds the compositor itself, `swaybar/` the status bar, `swaynag/` the small nag/notification window, and `swaymsg/` the command-line client. `common/` and `include/` hold shared code, and `protocols/` holds Wayland protocol definitions.

The control path is the part worth understanding before you adopt it. `swaymsg` talks to a running compositor over a socket and issues the same commands your config file uses. That means the configuration language and the runtime control language are the same thing, which is why scripting Sway behaviour does not require a plugin API. A shell script can call `swaymsg` and get the same effect as a keybinding.

The rendering and input layer is not in this repository. Sway depends on wlroots, hosted on gitlab.freedesktop.org, for the actual Wayland backend work. That split matters for upgrade planning: a Sway release and a wlroots version travel together, and the README points people who want to build the HEAD of Sway to a wiki page that covers building wlroots alongside it. Sway is written in C and licensed MIT, and releases are signed with the key E88F5E48 and published on GitHub.

Installing Sway and getting a first session running

The README gives two routes. The short one is a distribution package: install the package named "sway" for your distribution. The long one is a source build, and the README lists the dependencies: meson, wlroots, wayland, wayland-protocols, pcre2, json-c, pango, cairo, gdk-pixbuf2, swaybg, scdoc, and git. The README marks meson, wayland-protocols, scdoc and git as compile-time dependencies, and notes gdk-pixbuf2 is optional for additional system tray image formats, swaybg is optional for wallpaper, and scdoc is optional for man pages.

The build sequence is three commands, exactly as given in the README:

meson setup build/
ninja -C build/
sudo ninja -C build/ install

After that, configuration. If you already have an i3 config, the README says to copy it to `~/.config/sway/config` and it will work out of the box. If you do not, copy the sample configuration file, usually found at `/etc/sway/config`. The README points to `man 5 sway` for configuration details, and that man page is the real reference rather than the README.

Running it is a single command from a TTY or from a display manager:

sway

What you should see is a bare session with your configured keybindings active and no desktop chrome. If you copied an i3 config, the first thing to check is whether your status bar command still exists on the system. A config that launches `i3status` will launch it under Sway too, and whether it renders correctly is a separate question from whether Sway parsed the config.

Where the i3 compatibility promise breaks down

The README's compatibility claim is about the configuration file, and it is worth reading it precisely. It says an i3 config will "work out of the box." It does not say every i3 feature is implemented, and it does not enumerate the exceptions. That gap is the main practical risk for a new user, because the failure mode is silent: a directive Sway does not recognise may be ignored rather than reported, and you discover the problem when a keybinding does nothing.

The deeper limitation is architectural rather than configurational. Sway is a Wayland compositor, so X11 clients run through XWayland, and anything that reaches into the X server directly is outside Sway's control. Screen sharing, global hotkeys registered by an X11 application, and tools that manipulate X windows by window ID are the usual casualties. None of this is a Sway bug; it is what moving off X11 means. The README does not document a migration checklist or a rollback path, so the practical way to find out is to run your own workload.

A second constraint is the wlroots dependency. Because the rendering backend lives in a separate project, Sway's behaviour on unusual hardware or with newer protocol extensions depends on a component that releases on its own schedule. Building from source means building both.

Sway against i3 and against Hyprland

The most direct comparison is with i3, the project Sway is explicitly compatible with. The difference is the display protocol underneath: i3 is an X11 window manager and Sway is a Wayland compositor. That single change is responsible for everything else. Sway gets to control input, output and rendering directly, which removes a layer of X11 indirection, but it also means Sway cannot support X11-only clients natively and has to route them through XWayland. If your workflow is entirely X11 applications with unusual window manipulation needs, i3 remains the lower-risk choice because it is the environment those tools were written for.

The other comparison people make is with Hyprland, a different Wayland compositor. The distinction is configuration philosophy. Sway's configuration is the i3 configuration language, a plain text file with `man 5 sway` as its reference, and `swaymsg` as its runtime interface. Hyprland does not inherit i3's configuration format, so an i3 config is not portable to it. If the value you place on Sway is that your existing config keeps working, that value does not transfer. Choosing between them is largely a question of whether you want i3's model preserved or a different one.

Licence, releases and the cost of staying current

Sway is MIT licensed, which is permissive and places few obligations on redistributors beyond preserving the licence notice. That is a different posture from copyleft compositor projects, and it matters if you intend to ship Sway inside a product image. This is a description of the licence, not legal advice; read the LICENSE file in the repository for the actual terms.

Upgrade cost is driven by the wlroots coupling rather than by Sway's own release cadence. The recent release history shows 1.12 published on 2026-05-25, preceded by two release candidates in April 2026, and the last push to the repository was on 2026-09-21. Releases are signed with E88F5E48 and published on GitHub, so verification is possible without trusting a mirror. If you install from a distribution package, your upgrade path is the distribution's, and the version you get may lag the upstream release. If you build from source, the README's development setup page is the reference, and you should expect to rebuild wlroots as well as Sway when you move forward.

The configuration file is the part with the lowest migration cost and the highest ongoing cost. It is plain text, so it is versionable and diffable. It is also untyped, so a mistake is a silently ignored line rather than a startup error.

Editorial conclusion

Adopt Sway if you already run i3 and want Wayland without rewriting your keybindings, or if you want a compositor whose configuration is a plain text file rather than a plugin API. Do not adopt it if you depend on X11-only tooling, or if you expect the Xorg session's screen sharing and global hotkey behaviour to carry over untouched. Before committing, verify that your distribution's sway package matches the 1.12 release, check that wlroots is available at a version your build expects, and test your own i3 config against `man 5 sway` rather than assuming full compatibility.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. swaywm/sway on GitHub