Ignis: a Python and GTK4 widget framework for building a Wayland shell

A shell framework whose scope is set by the Layer Shell protocol

Ignis is a widget framework for building desktop shells, written and configurable in Python. The README lists its qualities in four bullets: easy to use, GTK4-based, batteries included with a lot of built-in Services and Utilities, and a loose coupling between the widgets you write.

The scoping comes from the supported desktop list, which is unusually explicit for a shell project. It works on wlroots-based Wayland compositors, with Sway given as the example, on Hyprland, on Smithay based compositors with COSMIC given as the example, and on KDE Plasma on Wayland. And then all other compositors that implement the Layer Shell protocol.

The exclusion list is given with a reason. Ignis is not supported on GNOME Wayland or on X11, because they don't support the Layer Shell protocol.

That single constraint explains the whole project. A panel or a bar that docks to a screen edge, with proper exclusive zones so that maximised windows do not overlap it, needs the compositor to reserve space for it, and Layer Shell is the protocol that does that. A compositor that does not implement it cannot host this kind of shell properly, which is why the project is candid that GNOME and X11 are out rather than offering a degraded mode.

The primary language is Python, the licence is LGPL-2.1-or-later, the default branch is main, and the last push was on 2026-10-20 with the most recent release v0.6.0 from 2026-08-01.

The Rust rewrite is the most important line in the README

The first thing on the page is a warning block, and it is not decorative.

Ignis is currently being rewritten in Rust, and the README points to a rust-rewrite branch. That is a substantial statement about the project's direction, and it changes how a reader should treat everything else on the page.

There is a second note right after the feature list, and the two together define the project's status. Ignis is mostly stable, but still a work in progress, and the API is subject to change. The breaking changes tracker is available in issue 60.

So there are two codebases in flight. The Python implementation on the main branch is what the released versions, currently v0.6.0, contain, and the Rust branch is where the project is heading. A user picking this up today has to decide which one they are building against, and a user who writes a configuration against the Python API has to expect that API to change.

The issue 60 tracker is the mechanism the project offers for making that manageable. It is a deliberate choice to publish a running list of breaking changes rather than a version history, which is a reasonable approach for a shell framework where the configuration surface is large and the users are technically capable.

The release history supports the picture. v0.5 in March 2025, v0.5.1 in May 2025, and then v0.6.0 in August 2026, with the last push on 2026-10-20, so the Python line is still receiving work while the rewrite proceeds.

Six dependencies and a Python that is the configuration language

The dependency list is short enough to read in full, and it says what the framework is built on.

click>=8.1.7
pycairo>=1.26.1
PyGObject>=3.50.0
loguru>=0.7.2
rich>=13.9.4

PyGObject is the bridge to the GObject introspection layer, which is how the framework reaches GTK4. pycairo is the Cairo 2D drawing library, used for the custom drawing that a shell needs for things like status areas and indicators. click provides the command line interface. loguru handles logging, and rich handles terminal output.

What that list does not contain is as informative as what it does. There is no GUI toolkit beyond GTK, no configuration file parser, because the configuration is Python, and no asynchronous framework, which means the event loop comes from the GObject main loop that GTK is built on.

The pyproject file confirms the shape. The project name is ignis, the license is LGPL-2.1-or-later, the author is linkfrg, the version is dynamic and comes from VCS through hatchling and hatch-vcs, and requires-python is 3.11 or later. The version hook writes a version file into the package, so the installed version tracks the git checkout rather than a hand-maintained string.

The typing story is also deliberate. The project is checked with mypy, configured with check_untyped_defs set to true, and it disables two error codes, no-redef and method-assign, with a comment giving the reason, that they are needed for the GObject.Property decorator. The mypy configuration also has an override for the gi.repository modules that disables assignment checking. In other words, the type checking is configured around the specific friction that GTK's property system creates in Python, which is a detail that tells you the authors have been fighting that particular battle rather than guessing about it.

Services and Utilities are the batteries in the batteries-included claim

The phrase batteries included is followed in the README by a parenthetical that says a lot, namely a lot of built-in Services and Utilities, and the capitalisation suggests these are named concepts in the framework rather than loose descriptions.

The word Services carries a specific meaning in the desktop shell world. A compositor provides the window management, the surface rules and the input handling, but it does not provide the things a panel needs to be useful: a status area with a clock, a battery indicator, a network and Bluetooth menu, a workspace switcher, a notification daemon, a launcher. Those are the services a shell has to implement, and the reason the term exists is that every shell framework ends up reimplementing the same set.

The Utilities side is the supporting layer, the small helpers that turn raw information into something displayable, and the framework's pitch is that a large number of them ship with it. The examples directory has one entry, bar, and the README describes it as a simple bar, with a screenshot. There is also a link to a real configuration, the author's own dotfiles repository, with a screenshot, which is a more useful reference than a minimal example because it shows what a shell actually looks like when it has been used for a while.

The example reference is the right thing to look at first, because a minimal bar example in a framework with built-in services can hide most of the work. A user's own configuration shows the parts that matter, which is how you learn what the framework expects of you and what it does for you.

Where the Layer Shell boundary leaves a real gap

The most useful thing about this project is also its most awkward: it does not run on the desktop most people have.

GNOME Wayland and X11 are excluded because they don't support the Layer Shell protocol. On X11 that is a matter of an older window model, and on GNOME it is a matter of GNOME's shell being its own implementation rather than something a third party panel can join. The consequence is that a large part of the Linux desktop population cannot use Ignis at all, and a user on Ubuntu with GNOME has to look elsewhere.

The supported list is not a small one. Sway and Hyprland cover a lot of the tiling window manager crowd, Smithay based compositors such as COSMIC are on the list, as is KDE Plasma on Wayland, and any other Layer Shell implementation is covered by the general statement. So the gap is GNOME-shaped, and within the supported world the framework is unremarkable in its ambition.

The alternative approach in the same space is worth naming on its own terms. AGS is credited in the Special Thanks section as the source of inspiration, and the difference is the language the shell is written in. The README credits AGS only for inspiration, and it does not describe its design; what Ignis states about itself is that it is written and configurable in Python. The choice of Python means the configuration is Python, the ecosystem is PyGObject and the GObject introspection world, and a user can import anything in the Python ecosystem directly into a widget.

That difference cuts both ways. Python brings a much larger standard library and a language people already use for scripting, and it brings the GObject introspection layer, where every GTK property is a Python object rather than a JavaScript proxy. It also brings the mypy friction visible in the configuration, and the packaging story of a Python library with a compiled dependency on GTK, which is why the project ships a flake.nix and a flake.lock alongside a requirements.txt.

The project is at version 0.6.0 with a rewrite in flight, so the pragmatic reading is that this is a project to watch and experiment with rather than to build a daily driver on top of today.

Editorial conclusion

Ignis fits a Linux user on Sway, Hyprland or a Layer Shell compositor who wants a desktop shell configured in Python, with the built-in services and utilities doing the work that a compositor does not provide, and it does not fit a GNOME or X11 user at all, since the project states Ignis is not supported on those because they don't implement the Layer Shell protocol. Before committing, read the breaking changes tracker in issue 60, because the project states the API is subject to change while the Python implementation is being rewritten in Rust, and check the examples/bar directory to see how much configuration a working shell actually needs.

Frequently asked questions

Official sources

1. ignis-sh/ignis on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases