wayle bundles the bar, notifications and OSD into one Wayland shell

One application instead of five desktop daemons

The usual Linux desktop layout is a stack of small programs that each own one piece of the interface: a bar, a notification daemon, an on-screen display, a wallpaper setter, and something to report battery, network and audio state. Each has its own configuration file, its own lifecycle, and its own idea of what a theme is.

wayle takes the opposite approach. The README describes it as a Wayland desktop shell with the bar, notifications, OSD, wallpaper and device controls built in, written in Rust with GTK4 and Relm4. That is the whole product in one sentence.

The audience follows from that choice. This is for someone who has already settled their compositor and wants the surrounding interface to behave consistently, with a single theme, a single reload mechanism, and modules that share the same process and the same configuration tree. It is not a window manager, and it does not replace the compositor, which it says outright in its requirements.

The shell is also extensible in a specific way. The documentation lists custom modules as shell-backed bar modules, so a module is not a plugin running in some other daemon, it is part of the shell, which is how the bar, the OSD and the settings GUI can all agree on the same state.

The project is at version 0.7.0, published as release v0.7.0 on 2026-07-25, after v0.6.0 on 2026-05-31 and v0.5.0 on 2026-05-28. The last push to the repository was on 2026-07-25.

wlr-layer-shell is the requirement that decides everything

There is one hard requirement, and it is worth understanding before anything else because it narrows the audience sharply.

wayle needs a Wayland compositor that implements the wlr-layer-shell protocol. Layer shell is the protocol that lets an application draw panels that the compositor treats as part of the desktop chrome rather than as ordinary windows, with defined anchors and exclusive zones. It is what a panel is built on.

The description calls the shell compositor agnostic, and in the sense of not hardcoding one compositor's configuration format that is fair. The protocol requirement is the real boundary though, and the README is clear about where the current support lies. Compositor-specific modules currently target Hyprland, Niri and Mango, and Sway support is planned soon.

That distinction matters for anyone evaluating this. Sway is a wlroots compositor with wlr-layer-shell support, so the protocol side is fine; the problem is the compositor-specific modules, the parts that know how to talk to a particular compositor's own IPC. Until Sway lands, a Sway user gets the generic parts of the shell and not the integrations.

The three that are supported have something in common: they expose their own IPC in ways a module can query. A module that knows how to ask Hyprland about the active window or workspace is doing something a generic layer-shell panel cannot, and that is the piece that is missing for Sway today.

Three ways into the same configuration

wayle can be configured in three ways, and the interesting part is that they are views of the same configuration rather than separate systems.

The README names them: configure it in config.toml, through the wayle-settings GUI, or with the wayle config CLI. The file lives at ~/.config/wayle/config.toml, and changes reload on save, so there is no restart step between editing a value and seeing it on screen.

The file itself is a TOML document with a layout section for the bar and per module sections, and the shape is simple enough to read in one glance:

[bar]
location = "top"
scale = 1.25

[[bar.layout]]
monitor = "*"
left = ["dashboard"]
center = ["clock"]
right = ["volume", "network", "bluetooth", "battery"]

[modules.clock]
format = "%H:%M"

Three things are visible in that snippet. The bar is positioned and scaled globally. Layouts are an array of per monitor blocks, and the wildcard monitor value means the same layout applies everywhere, which is how per monitor layouts are expressed when they differ. Within a layout, elements are placed into left, center and right regions by module name, so the ordering of a panel is a list of names rather than a drawing instruction.

For anyone who has configured a bar in a compositor's own config language, this is a different model. The unit of configuration is the module, and the bar is a container that arranges modules. Themes then apply across modules, because the styling layer is shared rather than per component.

Building from source takes two cargo install calls

There is a packaged route and there is a source route, and the source route is unusually explicit about what it needs.

On Arch there is a binary package, installed with:

yay -S wayle-bin

On other distributions the README documents installing Rust via rustup, then a set of system libraries, then the runtime daemons. On Debian and Ubuntu the library list looks like this:

sudo apt install git pkg-config cmake libgtk-4-dev libgtk4-layer-shell-dev \
  libgtksourceview-5-dev libpulse-dev libfftw3-dev libpipewire-0.3-dev \
  libudev-dev clang build-essential

The runtime daemons are separate from the libraries, and this is the part people miss. The battery, bluetooth, network, power and audio modules talk to bluez, NetworkManager, upower, power-profiles-daemon, pipewire and wireplumber, and those have to be running:

sudo systemctl enable --now bluetooth NetworkManager upower power-profiles-daemon

Each module needs its daemon, so a module for something you do not have installed is a module that cannot report anything.

The build itself is two cargo installs, because the shell and the settings GUI are separate binaries:

git clone https://github.com/wayle-rs/wayle
cd wayle
cargo install --path wayle
cargo install --path crates/wayle-settings
wayle icons setup
wayle panel start

The icons setup step comes before the panel for a reason. The bar draws module icons, and that step installs the icon sources the shell expects, which is also why the documentation has a whole page on custom icons and icon sources.

There is a distribution constraint worth noting before you start. Ubuntu 24.04 LTS does not package libgtk4-layer-shell-dev, so the README asks you to use Ubuntu 25.04 or later, or Debian 13. Fedora requires 42 or later, and Fedora Workstation already ships the runtime daemons while minimal and server installs do not.

The crate list shows how the shell is divided

The Cargo workspace is the clearest description of the project's internal structure, and it is worth reading as an architecture.

The workspace declares eleven members. crates/wayle-config holds the configuration, crates/wayle-derive provides the derive macros, crates/wayle-i18n handles translations, crates/wayle-icons the icon handling, crates/wayle-idle-inhibit the idle inhibition, crates/wayle-ipc the inter-process communication, crates/wayle-settings the GUI, crates/wayle-shell the shell core, crates/wayle-styling the theme engine, and crates/wayle-widgets the widgets, with the top level wayle/ crate for the binary itself. The sandbox directory is excluded from the workspace.

Two of those names carry a lot of information. wayle-shell means the shell is a first class part of the design rather than a bar with some extras, and wayle-ipc means there is an IPC layer, which is what makes a separate settings GUI possible as a different binary rather than a screen inside the same process.

The dependency list explains the implementation choices. GTK4 with the v4_12 feature and gtk4-layer-shell for the panel, relm4 with macros for the reactive component model, smithay for the Wayland side, grass as the CSS implementation, palette for colour handling, notify for filesystem watching, which is the mechanism behind reload on save, schemars for JSON schema generation of the configuration, minijinja for templating, i18n-embed with fluent for localisation, rusqlite with the bundled feature for storage, and clap for the command line.

The toolchain requirements are explicit too. The workspace uses edition 2024 with rust-version 1.93, so the Rust version on your machine has to be new enough.

Where a hand assembled panel setup differs

The alternative to wayle is not another shell, it is the arrangement most people already have: several independent programs, each owning one part of the interface, each with its own configuration file and its own reload behaviour.

The difference in approach is where the state lives. In a separate arrangement, the bar knows about the network manager and the notification daemon knows about the mail client, and the theme is applied once per program. In wayle, the modules run inside one shell, so the styling layer is shared, the configuration is one TOML file with one schema, and a change to the theme is a change in one place. The IPC crate is the visible sign of that design, since the settings GUI and the shell exchange state rather than each holding their own copy.

The cost of that consolidation is real and worth naming. A single shell has a single failure domain, so a module that misbehaves can affect the rest of the interface, and you give up the ability to swap one component without touching the others. You also inherit the shell's requirements: the layer-shell protocol, the Rust toolchain if you build from source, and the system libraries. A compositor that already provides a perfectly good bar natively needs none of that.

So the question is not which is better in general. It is whether you want your desktop chrome to be one coherent application with one config file and one theme, or a set of small programs that each do one thing and do not interfere with each other. wayle is a bet on the first.

Pre-1.0 versioning and what an upgrade costs you

wayle is version 0.7.0, and the release history is short and recent: v0.7.0 on 2026-07-25, v0.6.0 on 2026-05-31, and v0.5.0 on 2026-05-28. The last push to the repository was on 2026-07-25, the same day as the newest release, and the repository is not archived.

Pre-1.0 versioning means the project is not promising a stable interface yet, and the pace of the release history suggests configuration and behaviour are still moving. That is normal for a shell in this stage of development, and it is the main thing to weigh against the convenience of a single configuration file. A config.toml that is comfortable today is a config.toml that may need editing after a minor release.

The documentation structure is designed for that reality. There are separate pages for editing config, which covers file layout, live reload, imports and CLI editing, for bars and layouts, which covers per monitor layouts, groups and classes, for themes with their colour tokens and theme files, for custom icons and icon sources, for custom modules, for the CLI with every subcommand, and for the full configuration reference at wayle.app/config. Every field is documented there, which is the place to check when a config file stops behaving as expected.

The licence is MIT, which is permissive enough for personal use, for redistribution of the binary and for use inside a larger project, with the usual obligation to keep the copyright and licence notice. The repository also carries a LICENSE file, and the Cargo workspace repeats the MIT designation in the package metadata.

One small thing to expect when you follow the getting started instructions. The repository carries a Repology badge for packaging status, so check whether your distribution already packages wayle before you build it yourself, and use the getting started guide for the library version reference if your distribution differs from the ones listed.

Editorial conclusion

wayle suits someone on a wlr-layer-shell compositor who wants one configurable place for the bar, the notification flow and the on-screen display instead of several separate programs, and it suits people who prefer editing config.toml with live reload over clicking through settings panels. It is the wrong tool for a compositor without wlr-layer-shell support, and the wrong tool for Sway today, because Sway support is described as planned rather than delivered. Before you commit, check that your compositor implements wlr-layer-shell, confirm the runtime daemons your modules need are present on your distribution, and read the configuration reference at wayle.app/config to see how much of the behaviour lives in the file rather than in the GUI.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wayle-rs/wayle on GitHub