SwayFX: a Sway fork that swaps wlr_renderer for GLES2 effects

What SwayFX adds on top of Sway, and who that is aimed at

Sway's stated restriction is that it only includes functionality that existed in i3. SwayFX treats that as the problem to solve. The README says the fork "ditches the simple wlr_renderer, and replaces it with our fx_renderer, capable of rendering with fancy GLES2 effects." Everything the project adds follows from that one substitution: blur, anti-aliased rounded corners on corners, borders and titlebars, shadows, dimming of unfocused windows, and per-layer effects so panels and notifications can be blurred too.

The audience is narrow and specific. If you are happy with Sway's appearance and only want i3 compatibility, SwayFX gives you nothing except a larger dependency graph. If you have looked at Hyprland screenshots and wanted the same visual vocabulary while keeping Sway's config syntax, keybindings and IPC, this fork is aimed at you. The README frames contribution scope the same way: the maintainers ask for "eye-candy type improvements" and suggest raising an issue before building anything outside that focus. That is a deliberate boundary, not an accident, and it tells you what will and will not get merged.

fx_renderer, scenefx and the extra dependency you inherit

The mechanism is a renderer swap, but the swap is not self-contained. The manual dependency list includes scenefx, a separate project by the same author, alongside wlroots, wayland, wayland-protocols, pcre2, json-c, pango and cairo. So SwayFX is not Sway plus a patch file. It is Sway plus an effects library that has to be built against a matching wlroots, and the container build makes the version coupling explicit: compose.yml passes WLROOTSVERSION 0.19.0, WLROOTSLIBVERSION 0.19, SCENEFXVERSION 0.4.1 and SCENEFXLIBVERSION 0.4 as build arguments. That is the real architecture story. The compositor, the scene graph library and the effects layer move together, and a mismatch is a build failure rather than a runtime warning.

The configuration surface reflects the same layering. Global effects are plain commands. Per-application effects go through layer_effects, which targets a layer shell namespace, and the README notes that gtk applications are likely to report the namespace "gtk-layer-shell" rather than their own name. You can discover the real namespaces at runtime with swaymsg -r -t get_outputs piped into jq. That is a two-step workflow: query, then write the rule.

Building SwayFX from source with meson and ninja

The README's manual path is short. Install the dependencies listed above, then run the three standard commands. scdoc is a compile-time dependency only if you want man pages, and gdk-pixbuf2 is optional for extra system tray image formats.

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

After install, the README notes that on systems without logind or seatd you need to set the suid bit on the binary, and that SwayFX drops root permissions shortly after startup:

sudo chmod a+s /usr/local/bin/sway

If you have Nix, the README offers a shorter route that avoids installing dependencies by hand. The flake builds the compositor and puts the binary under result:

nix build
./result/bin/sway

For a development shell instead, `nix develop` brings up the environment without the manual dependency list. Debian users are pointed at INSTALL-deb.md rather than given steps inline. Fedora users are pointed at the swayfx copr and the Terra repository, which is the only prebuilt route the README names.

A first config: blur, corners and a Waybar layer rule

Configuration is Sway's config file with new directives. Start with global blur and corner radius, then add a per-layer block so your panel matches. The README gives this structure for a layer application:

layer_effects "waybar" {
    blur enable;
    blur_xray enable;
    blur_ignore_transparent enable;
    shadows enable;
    corner_radius 20;
}

blur_xray is the setting most people get wrong. The README describes it as making floating windows blur based on the background rather than the windows below, and adds the blunt aside "You probably want to set this to disable :)". The same block form is available for dimming unfocused windows, with separate colors for unfocused and urgent states:

dim_inactive_colors.unfocused #000000FF
dim_inactive_colors.urgent #900000FF
titlebar_separator enable

Two constraints matter here. Layer effects can also be applied live through swaymsg, but the README states you can only set one effect at a time that way, so multi-effect blocks belong in the config file. And effect tuning lives in bounded ranges: blur_passes and blur_radius accept 0 to 10, blur_noise 0 to 1, blur_brightness, blur_contrast and blur_saturation 0 to 2, shadow_blur_radius 0 to 99, and animation_duration_ms 0 to 5000. Those ceilings are worth reading before you copy someone else's dotfiles, because values outside the range are not the author's intent.

Where SwayFX is the wrong tool

The README is unusually candid about one feature. scratchpad_minimize, which makes docks and taskbars interpret minimize and unminimize requests correctly, carries the note: "we recommend keeping this setting off, as there are many kinks to iron out here". If correct minimize semantics are what you came for, the project itself is telling you the feature is not finished. Take that at face value.

The bigger limitation is packaging. The README names prebuilt routes for Fedora only, through the copr and Terra. Everyone else builds from source, and the build pulls scenefx and a specific wlroots. If your distribution ships a wlroots version that does not match what scenefx expects, you are now maintaining a graphics stack, not installing a window manager. That is a real change in the kind of project you are running.

There is also a rendering cost that the README does not quantify. Blur passes, shadows and anti-aliased corners are GLES2 fragment work applied per surface. On a low-power integrated GPU driving a high-resolution display, that is exactly the workload that gets expensive. The project documents the controls, not the frame budget, so you have to measure on your own hardware. And shadows_on_csd carries its own warning that the shadow might not fit some windows, which is the kind of cosmetic mismatch that looks like a bug to anyone watching your screen.

SwayFX compared with Sway and Hyprland

Against Sway, the difference is the renderer and nothing else. SwayFX inherits Sway's config language, IPC, swaybar, swaynag and swaymsg, so a Sway config mostly carries over and you add the new directives on top. The cost is that you are now tracking a fork, and SwayFX has to absorb upstream Sway changes itself. The README's acknowledgement section thanks the Sway maintainers and describes the team as "a humble group of Sway enthusiasts", which is an accurate description of the maintenance model: a small group carrying a large upstream.

Against Hyprland, the split is philosophy rather than features. Hyprland is its own compositor with its own configuration format and its own ecosystem. SwayFX keeps i3-style syntax deliberately. If your config, scripts and muscle memory are built around Sway, that continuity is the entire value proposition, and rewriting them for a different compositor is the thing you are avoiding. If you have no Sway investment, the continuity argument evaporates and you should compare the two on their own terms rather than on the fork's.

A third option worth naming: stay on plain Sway and accept the look. That is not a compromise if you never wanted blur. It is the option with the smallest dependency graph and the shortest path to upstream fixes.

Licence, upgrade cost and what a release actually means

SwayFX is MIT licensed, which is the same permissive family Sway uses and places few restrictions on how you redistribute or modify it. That is a statement about the licence text, not legal advice about your situation; if you ship a modified compositor, read the LICENSE file in the repository rather than this paragraph.

The practical upgrade cost is the version coupling. The container build pins wlroots 0.19.0 and scenefx 0.4.1, and the manual dependency list names scenefx without a version, so the README leaves you to work that out. When wlroots moves, scenefx has to move with it before SwayFX can. That means an upgrade is not a single package bump. It is a coordinated rebuild of three components, and the release cadence reflects it: 0.5.2 and 0.5.3 landed days apart in June 2025, then 0.6 arrived on 2026-08-05. The repository's last push was on 2026-09-27, so work has continued after that release, but the README does not document a rollback path if a new build breaks your session. Keep your previous build until the new one survives a full day of real use.

Editorial conclusion

Adopt SwayFX if you already run Sway, want blur, rounded corners and shadows without leaving the i3-style config language, and can build scenefx alongside it. Do not adopt it if you need distribution-packaged binaries you can update with your normal package manager, or if you depend on the exact wlroots release your distro ships, because the container build pins wlroots 0.19.0 and scenefx 0.4.1 and the README's manual path expects you to supply both. Before committing, verify three things on your own machine: that scenefx builds against your wlroots, that your GPU stack handles the GLES2 passes at your monitor resolution, and whether scratchpad_minimize is worth enabling given the README's own warning that it has kinks to iron out.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. wlrfx/swayfx on GitHub