Sway is a tiling Wayland compositor for Linux and other Unix-like systems that serves as a drop-in replacement for the i3 window manager. On the Linux desktop it combines the roles of display server, window manager and compositor in one process, arranging windows automatically into non-overlapping tiles that the user controls mostly from the keyboard.
Sway reads configuration files that are largely compatible with i3, so users can move from an X11 session to Wayland with minimal relearning. It is built on wlroots, a modular library for writing Wayland compositors that the Sway project originally created and that now underpins many other compositors.
How Sway works as a Wayland compositor
Under Wayland, the compositor is the display server: it talks directly to the kernel’s graphics and input subsystems and decides where every client surface appears. Sway therefore performs work that on X11 was split between the X server, a window manager such as i3 and a separate compositor.
Sway uses DRM and KMS to set display modes, libinput to handle keyboards, mice and touchpads, and wlroots to manage outputs, rendering and the Wayland protocol objects. Clients draw their own buffers and hand them to Sway, which composites them into the final frame. Legacy X11 applications run through XWayland, an X server that acts as a Wayland client.
Window placement follows a tree-based layout model inherited from i3. Each workspace holds a tree of containers, and every container splits its space among its children horizontally, vertically, as stacked title bars or as tabs. New windows are inserted next to the focused one, so the layout grows predictably without manual resizing.
The table below lists the main components that a typical Sway session relies on and the role of each one.
| Component | Layer | Role |
|---|---|---|
| wlroots | Compositor library | Outputs, rendering, input and protocol handling |
| libinput | Input stack | Keyboard, pointer, touchpad and tablet events |
| DRM and KMS | Kernel graphics | Mode setting and page flipping on displays |
| XWayland | Compatibility | Runs X11 applications inside the Wayland session |
| swaymsg and IPC | Control interface | Sends commands and queries the layout tree |
Layouts, workspaces and the configuration file
Sway is controlled through a plain-text configuration file, usually stored at ~/.config/sway/config, that defines key bindings, workspaces, output and input settings, and programs to start. Every line is a Sway command, and the same commands can be sent at runtime with swaymsg.
The four container layouts determine how sibling windows share space. Users switch between them with a single key binding, and floating windows can still be used for dialogs or utilities that should not tile.
| Layout | Arrangement | Typical use |
|---|---|---|
| splith | Side by side, horizontal split | Code editor beside a terminal |
| splitv | Stacked vertically | Two logs or terminals above each other |
| tabbed | One window visible, tabs on top | Many browser or document windows |
| stacking | One window visible, title bars stacked | Quick switching on narrow screens |
| floating | Free position outside the tree | Dialogs, pickers and small utilities |
Unlike i3, Sway configures displays and input devices directly. The output command sets resolution, refresh rate, position, rotation and fractional scaling per monitor, while the input command sets keyboard layouts, pointer acceleration and touchpad gestures without extra tools such as xrandr or xinput.
- Workspaces are numbered or named and can be pinned to specific outputs.
- The scratchpad hides a window and recalls it with one key, useful for a notes terminal.
- Criteria rules such as
for_windowset behavior for matching applications automatically. - Modes temporarily change key bindings, for example a resize mode.
Sway compared with i3 and other tiling compositors
Sway’s closest relative is i3, whose concepts, commands and IPC protocol it reproduces on Wayland. The main differences come from the display protocol rather than from window management, which is why the comparison with Hyprland and full desktop environments is more instructive.
| Option | Display protocol | Tiling model | Design focus |
|---|---|---|---|
| Sway | Wayland | Manual tree, i3-compatible | Stability and i3 compatibility |
| i3 | X11 | Manual tree | Minimal, mature X11 tiling |
| Hyprland | Wayland | Dynamic tiling with animations | Visual effects and features |
| GNOME | Wayland or X11 | Floating with snapping | Integrated full desktop |
| KDE Plasma | Wayland or X11 | Floating with optional tiling | Highly configurable desktop |
Sway deliberately keeps a conservative feature set: it avoids decorative animations and rarely adds functionality that i3 lacks. This makes it attractive for users who value predictable behavior and low resource use, whereas Hyprland appeals to those who want effects and newer features.
Ecosystem tools and practical setup
Sway is a compositor, not a complete desktop, so a working session combines it with small companion programs. The Sway project maintains several of them, and the wider wlroots ecosystem supplies the rest.
The following table shows common companion tools and the function each provides.
| Tool | Function | Notes |
|---|---|---|
| swaybar | Status bar | Built in; often replaced by Waybar |
| swaylock | Screen locker | Uses the session lock protocol |
| swayidle | Idle management | Triggers locking and display power off |
| swaybg | Wallpaper | Sets a background per output |
| Launchers such as wofi or fuzzel | Application launcher | Replace dmenu from i3 setups |
Screen sharing in browsers and video-call applications relies on xdg-desktop-portal-wlr together with PipeWire, because Wayland does not let clients capture the screen directly. Users migrating from i3 should also replace X11-only utilities, for example clipboard managers and screenshot tools, with Wayland-native equivalents.
Limitations and common pitfalls
Sway’s main limitations stem from its strict adherence to Wayland principles and from hardware support. The project officially supports only GPUs with open-source kernel drivers, and running on proprietary NVIDIA drivers requires the --unsupported-gpu flag, with bugs that the developers do not treat as their responsibility.
Other recurring issues come from X11 assumptions in older software. Applications that rely on global hotkeys, screen capture or window positioning may behave differently, and XWayland windows can appear blurry under fractional scaling because they are rendered at a lower resolution and then scaled.
- Copying an i3 configuration unchanged can fail on X11-specific lines such as xrandr calls.
- Forgetting portal packages breaks screen sharing in browsers.
- Starting Sway without a seat manager such as seatd or systemd-logind prevents device access.
- Expecting desktop features such as a settings panel leads to frustration; Sway is configured in text.
The idea in brief
Sway is a program that arranges every window on the screen for you. Instead of dragging windows around and letting them overlap, Sway places them side by side like tiles on a floor, so each window always gets its own clear space.
You control it mostly with keyboard shortcuts, which makes it fast once learned. It is the modern Wayland version of an older tool called i3, so people who already know i3 can switch with almost no relearning.
A practical scenario
A backend developer works on a laptop with a 14-inch 2880 by 1800 display and an external 27-inch monitor. On the previous i3 setup, mixed scaling between the two screens was awkward, so the developer migrates to Sway and copies the old i3 configuration, removing only the xrandr and X11 clipboard lines.
In the Sway configuration, the developer sets the laptop panel to scale 1.5 with the output command, pins workspaces 1 to 3 to the external monitor and keeps a terminal in the scratchpad for quick notes. Swayidle locks the screen after 10 minutes, and the portal packages enable screen sharing in video calls.
The result is a consistent keyboard-driven workflow across both displays, with sharp text on the high-density panel and the same shortcuts used for years under i3.