nwg-shell: a GTK3 desktop shell for sway and Hyprland

A desktop assembled from twelve small GTK programs

nwg-shell is a GTK3-based shell for sway and Hyprland Wayland compositors, and the project description is effectively an inventory of what it puts on your screen.

The centrepiece is a common configuration tool, nwg-shell-config, which allows you to configure the system in a graphical UI. Around it sit the components: nwg-panel, the system panel; nwg-drawer, the application launcher; nwg-dock, the system dock; and nwg-menu, an XDG-style menu.

Then the native tools, which are the part that makes it a shell rather than a panel kit: nwg-look, a look and feel GTK settings editor; nwg-displays, a display configuration tool; Azote, a wallpaper manager; nwg-clipman, a clipboard history manager; nwg-icon-picker, an icon browser with textual search; nwg-readme-browser, a documentation viewer; and nwg-hello, a login manager.

And in the background, scripts and utilities: autotiling, a script for sway that automatically switches the horizontal and vertical window split orientation, and gospuinfo, a command to display system usage info.

That last pair is a good clue about the project's character. A bare sway installation is a window manager, a bar and a keybinding file. nwg-shell takes the position that a desktop is a collection of small programs, each replaceable, and that the job of the project is to make sure a set of them agree with each other and come pre-configured. The autotiling script in particular is the kind of small thing that a tiling user would otherwise write for themselves in an afternoon and then never touch again.

The project also uses third-party software rather than reimplementing it, naming swaync as the notification centre and gtklock and swaylock as screen lockers.

This repository is the installer, not the applications

The most important structural fact about the repository is stated in the description and confirmed by the package manifest.

The nwg-shell package itself acts as a metapackage and installer of default configuration files. So what you clone here is not the panel, not the launcher and not the config tool. It is the thing that pulls those together, ships the skeleton configuration, and puts the result on your system.

The top-level listing makes the same point. There is an `install/` directory, an `install.sh` script, a `setup.py`, a `nwg_shell/` Python package, a `scripts/` directory, and a `nwg-readme.desktop` desktop entry, plus a `nwg-shell.jpg` screenshot.

The `setup.py` is where the shape becomes concrete. The package is named `nwg-shell` at version 0.5.50, the description is a GTK3-based shell for the sway Wayland compositor, and the author is Piotr Miller with the MIT licence and `python_requires='>=3.6.0'`. The `install_requires` list is empty, which tells you the package itself pulls in nothing, and the work is done by the installer instead.

What the manifest does carry is the skeleton. The `package_data` list is the interesting part, because it enumerates the default configuration that ships with the shell: `skel/stuff/*`, `skel/config/nwg-dock/*` and a separate `skel/config/nwg-dock-hyprland/*`, `skel/config/nwg-drawer/*`, `skel/config/nwg-panel/*`, `skel/config/nwg-look/*`, `skel/data/nwg-look/*`, `skel/data/nwg-shell-config/*`, and then per-component directories for `sway`, `hypr`, `nwg-displays`, `swaync`, `foot`, `gtklock` and `gtk-3.0`.

That list is the actual product. There is a separate Hyprland variant of the dock configuration, there is a sway configuration and a Hyprland configuration, and there is a terminal configuration for foot and a GTK 3.0 settings directory. A user who installs this gets a coherent desktop, and the coherence comes from these files being maintained together rather than assembled one at a time.

Two entry points, one of which is a GUI script

The entry points in the manifest are short and reveal the two roles the package plays.

entry_points={
    'gui_scripts': [
        'nwg-shell = nwg_shell.main:main',
        'nwg-shell-installer = nwg_shell.installer:main'
    ]
}

Both are registered as `gui_scripts` rather than plain `scripts`, which in setuptools terms means they are launched without a console attached. On Linux that distinction is close to cosmetic, but it signals the intent: these are graphical entry points, not command line tools, and they are meant to be launched from a menu.

`nwg-shell-installer` is the one that matters first for a new user. `nwg-shell` is the launcher for the shell's own configuration experience, which the project describes as the common configuration tool, nwg-shell-config, presented through this entry point.

The installer and the shell have different jobs, and the distinction is worth understanding before you install anything. The installer deploys the default configuration files, the skeleton, to your home directory and sets up the components. The shell entry point is the graphical front end to the configuration tool that comes after, where you then adjust the panel, the dock, the launcher and the rest.

So the workflow is a two-step one, and a user who skips the first step will find the config tool editing configuration that was never written. The install.sh script at the root of the repository and the `install/` directory are the other route to the same place, for anyone who would rather not go through the Python entry point.

The `docs` directory does not exist in this repository, but the project documentation lives on the project website, and the install instructions are on the wiki, which the README points to rather than repeating.

Packaging, licensing and how the project talks to its users

Three things in the README are about the project as an organisation rather than as a piece of software, and they matter for anyone considering depending on it.

The first is packaging. The README points to the Repology badge for a vertical all-repos view, and the packaging status is therefore visible across distributions rather than being confined to one. For a project made of many small pieces, that matters, because the components need to be installable and updatable on a normal desktop, and a metapackage that is not in your distribution's repository is a metapackage you have to build yourself.

The second is licensing. The shell components are provided under the terms of the MIT License, unless otherwise specified for a certain component. That qualifier is doing real work, because a project that also ships third-party components and default configurations for other people's software will have some components with different terms, and the phrase tells you to check per component rather than assume. The project metadata records the licence as a custom one that GitHub cannot classify, and the LICENSE file at the root is the place to read the actual terms.

The third is how support works, and it is worth reading because it is old-fashioned in a good way. Use Discussions to see the CHANGELOG and announcements, share ideas and ask for support. Use the IRC channel #nwg-shell on OFTC, with a webchat link for a quick jump. The CHANGELOG being in the Discussions area rather than in a file is unusual, and it means the release history is somewhere a user actually reads.

The README also carries a JetBrains sponsorship notice, so part of the maintenance is funded rather than purely volunteer time, and the donate link points at Liberapay.

On versions, the release history is v0.5.50 from 2026-03-31, v0.5.49 from 2025-06-06 and v0.5.48 from 2025-04-17, and the last push was on 2026-09-29, so the repository is being worked on more recently than the last tag.

Where nwg-shell is the wrong choice

The first case is a user of a conventional desktop environment. Everything here is built for a wlroots-based tiling compositor on Wayland, specifically sway and Hyprland, and the components assume that model of interaction. A GNOME, KDE Plasma or Xfce user already has a panel, a launcher, a settings application and a screen locker, and installing this would mean replacing a coherent desktop with a collection of parts.

The second case is someone who wants a minimal setup. A sway user who wants one bar and a launcher does not need a configuration tool, a wallpaper manager, a clipboard history manager, an icon browser with textual search and a documentation viewer. The value of the shell is that the pieces are already agreed with each other, and that value only exists if you take all of them.

The third case is a user who does not want the default configuration. The metapackage ships a skeleton, and the whole design is that you start from the defaults and adjust them. A user who has already built their own sway config, with their own panel and their own keybindings, will find the installer asking them to accept files that are already there, and the value of the project drops to the few components they were missing.

The fourth is a distribution where the packages are not available and the build is awkward. The metapackage is the convenient path, and Repology shows where it is packaged. Where it is not, you are installing the components individually or building this yourself, and the metapackage's main value, the coordinated default configuration, is the thing you lose.

One more practical note. The shell leans on third-party software for the notification centre and the screen lockers, swaync, gtklock and swaylock, and each of those has its own configuration. The default skeleton includes directories for swaync, foot, gtklock and gtk-3.0, which means the install touches the configuration of programs it does not own. A user with an existing swaync setup should read the wiki installation page carefully before running the installer, because the point where a default configuration overwrites an existing one is exactly the kind of thing that is easy to discover late.

Editorial conclusion

nwg-shell fits a sway or Hyprland user who wants a complete desktop rather than a bare compositor, and it fits one who wants the configuration to be editable through a graphical tool instead of by hand. It does not fit a GNOME, KDE or X11 user, and it does not fit someone who wants a minimal tiling setup. Before you install, read the wiki installation page, because the repository is a metapackage and installer rather than the components themselves, and check the third-party dependencies the shell relies on, since the notification centre and the screen lockers are separate projects with their own configuration.

Frequently asked questions

Official sources

1. Issues
2. nwg-piotr/nwg-shell on GitHub
3. README
4. Releases