# nwg-panel: a GTK3 panel for sway and Hyprland with a GUI editor

> nwg-panel is a panel for the sway and Hyprland Wayland compositors that ships a graphical configuration program, so panel modules can be set up without hand editing files. It is a good fit for a customisable desktop panel, while the tray module still collides with KDE's kded6 on a mixed desktop.

**nwg-piotr/nwg-panel** — GTK3-based panel for sway and Hyprland Wayland compositors

- Repository: https://github.com/nwg-piotr/nwg-panel
- Stars: 782 · Forks: 62
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/nwg-piotr-nwg-panel

## A panel aimed squarely at sway and Hyprland

nwg-panel is a GTK3-based panel for the sway and Hyprland Wayland compositors. It is part of the nwg-shell project, and it ships with a graphical configuration program that the README says frees the user from the need to manually edit configuration files.

That last point is the design decision that defines the project. A panel is a grid of modules: a clock, a workspace switcher, a taskbar, a system tray. Each of those needs a configuration file describing what to show and what to run. The graphical program is the response to the fact that those files are tedious to write by hand.

The two target compositors are the reason the tool is not generic. A panel that talks to a compositor over its IPC socket, lists workspaces, moves windows between them, toggles floating and fullscreen, and shows a marker for X11 windows is written against a specific compositor model. nwg-panel supports sway and Hyprland, and the module list includes entries specific to each, with a SwayMode indicator for sway bindings modes and a HyprlandSubmap indicator for Hyprland submaps.

The audience is therefore a user who has already chosen one of those compositors and wants a panel that looks like the one they want rather than the one the compositor shipped with. The language is Python, the licence is MIT, and the repository is not archived.

## A dozen modules, and the executor as the escape hatch

The README is candid about scope: there are a dozen modules and no plan for many more, because the many minor tasks users request a module for may be easily done with executors.

That is the key architectural point. Rather than growing a module per feature, nwg-panel offers an Executor module that runs user-provided code and displays the output in the panel as an icon and text. The Wiki holds the details and executor examples. For a user who wants a battery percentage in a specific format, a network speed readout, or a script of their own, the executor is the intended route, and the panel is designed so that the module list does not need to grow.

Among the modules that do exist, the system oriented ones are grouped in the Controls module: a brightness slider, a volume slider with per-application sliders, a battery level with a low level notification, a system processes viewer, user-defined custom items, and a user-defined drop-down menu which is the power menu by default. A separate brightness slider exists for per-monitor use and supports backlight through ddcutil.

The rest cover the desktop surface. Clock comes with a calendar popup. Custom button is a user-defined graphical or textual button bound to an action, used by default as the application launcher. The Sway, Hyprland and Niri taskbars show a label with an icon for every running window, with workspace number, split orientation on sway and an X-windows marker, and a right-click menu to move windows between workspaces, toggle floating and fullscreen, and close windows. Sway and Hyprland workspaces show labels to navigate between workspaces with a marker for non-empty ones.

## Media, weather, wallpaper and scratchpad modules

The remaining modules cover the parts of a desktop that a panel traditionally takes an interest in, and they are worth reading closely because each one names an external dependency.

The Playerctl module displays an icon and a label for the currently played tune, together with back, play-pause and forward buttons, which means it delegates to playerctl rather than talking to media players directly. The Openweather module displays a weather forecast from OpenWeatherMap and weather alerts from weatherbit.io for given locations, so it depends on two external services and their keys. The Scratchpad module shows information about the current scratchpad content and lets you open scratchpad windows, which is a sway concept.

RandomWallpaper is the most configurable of the set. It pulls random wallpapers from a local folder or from the wallhaven.cc service, refreshes them on startup, on demand or at a given time interval, shows information about the remote image, and can save the image to a local folder of your choice.

Two smaller modules complete the picture. SwayMode is a simple indicator of a sway bindings mode other than default, and HyprlandSubmap is the same idea for Hyprland. The KeyboardLayout module switches between layouts defined as xkb_layout for sway or kb_layout for Hyprland, with comma separated values such as pl,us,de. The Pinned module shows buttons for pinned items from nwg-drawer or nwg-menu, and the Menu Start module integrates the XDG-style nwg-menu.

The DWL tags module is marked deprecated and no longer supported, and the README says it will be deleted in the future. A separate entry point, nwg-dwl-interface, remains in the packaging, so the tool has not fully let go of that lineage yet.

## The tray module and the kded6 conflict

The Tray module is an SNI system tray module, and it is the part of nwg-panel most likely to misbehave on a machine that is not a pure sway or Hyprland session.

The documented failure mode is precise. If kded6 is running, for example because it was started by launching Dolphin, it may register org.kde.StatusNotifierWatcher and prevent nwg-panel from owning the system tray. Two applications are then competing to be the StatusNotifierWatcher host, and the tray icons end up in the wrong place or nowhere.

The fix is to stop the other process:

```bash
pkill kded6
```

That is a blunt instrument, since kded6 is a KDE service daemon that other things may depend on, and the README points at an issue thread for more context. The underlying lesson is worth carrying to any panel: on Linux, the system tray is a single-owner resource, and two desktop stacks on one session will fight over it.

The packaging reflects that the tray is optional rather than core. The tray dependency, dasbus, sits in an extras_require entry named tray rather than in the main dependency list, and the setup metadata notes that the tray is skipped without it. A user on a plain sway or Hyprland session can therefore install the panel without pulling in a D-Bus service library at all.

## Installing from a distribution package or the install.sh script

The README recommends distribution packages first. It carries a Repology packaging status badge, and the installation section says that if nwg-panel has not yet been packaged for your Linux distribution, you may install it by cloning the repository and running the install.sh script.

So there are two paths, and the order matters. A packaged install is the better one, since it arrives with a desktop entry, a systemd unit and the icon and language files in the right places. The repository itself contains exactly those artefacts, which you can see in the file list: nwg-panel-config.desktop, nwg-panel.service, nwg-panel.svg, nwg-processes.desktop and nwg-processes.svg, alongside install.sh and uninstall.sh.

The Python dependencies are pinned in the requirements file, and they are not light:

```bash
PyGObject~=3.42.0
psutil~=5.9.0
i3ipc~=2.2.1
```

PyGObject is the GTK 3 binding, psutil covers the process and system information that the Controls module and the processes viewer need, and i3ipc is the IPC client that talks to the compositor. The dasbus entry in the same file belongs to the optional tray extra.

After installation the panel is configured graphically rather than by editing files, and the configuration program is a separate entry point from the panel itself, so the two are launched in different ways.

## Entry points, the Python floor and what each command does

The packaging metadata describes four console entry points, and reading them explains the layout of the source tree.

The first is nwg-panel, mapped to nwg_panel.main:main, which runs the panel itself. The second is nwg-panel-config, mapped to nwg_panel.config:main, which is the graphical configuration program. The third is nwg-dwl-interface, mapped to nwg_panel.dwl_interface:main, the leftover of the deprecated DWL support. The fourth is nwg-processes, mapped to nwg_panel.processes:main, which is the standalone system processes viewer rather than the panel module that shows the same information.

The Python version floor is set with python_requires='>=3.9', and the source comment explains why: f-strings everywhere, which need 3.6, and list[str] annotations in the tray, which need 3.9.

The dependency comment is equally useful. It records that i3ipc and requests are imported unconditionally by modules that main.py always imports, naming the scratchpad, sway_mode, playerctl and random_wallpaper modules, and that dasbus is optional because the tray is skipped without it. Those are the kinds of comments you only get when someone has debugged an import failure in a minimal install.

The repository also ships a test.ipynb notebook, which suggests some of the exploratory work is documented in notebook form rather than in a test suite.

## Where nwg-panel is the wrong choice

The most obvious mismatch is a desktop that is not sway or Hyprland. The panel is written for Wayland compositors with a sway style IPC model, and the workspace, taskbar and mode modules all assume that model. On GNOME or on a plain X11 session, a different panel is the sensible starting point.

The second mismatch is a preference for text configuration. The graphical configuration program is the reason this project exists rather than a plain JSON panel, but it is not an advantage for everyone. If you are comfortable writing the configuration files directly, you get the same modules without the editor, and you can keep the configuration in a dotfiles repository where it is reviewed and diffed like any other file. The GUI is a convenience, and it is optional in that sense.

The third is a machine where the system tray is contested. On a session where kded6 runs, the tray module needs a process kill to work, and that is not a state you want a daily driver in.

There is a fourth consideration for anyone embedding this in a larger setup: nwg-panel is one component of the nwg-shell project, and its companion tools, nwg-menu, nwg-drawer and the others, are separate repositories. The Panel module integrates nwg-menu, the Pinned module reads items from nwg-drawer or nwg-menu, and the README points to the nwg-shell site. Adopting the panel alone is possible, but you are taking one tool from a suite that assumes a certain desktop layout.

## Conclusion

Adopt nwg-panel if you run sway or Hyprland and want a panel you can configure through a graphical program rather than by editing files, especially if you need the executor mechanism, the workspace and taskbar modules, or the SNI tray. Do not pick it for a GNOME or KDE session, since the tool is built for Wayland compositors with a sway style IPC model, and be aware that the tray module loses to kded6 on a mixed KDE desktop until you stop that process. Before you configure it, check whether your distribution already packages nwg-panel, since the README points to a packaged install first and to install.sh only as the fallback, and confirm that Python 3.9 or newer is available because the setup metadata sets that floor.

## FAQ

### What is nwg-panel and which compositors does it support?

nwg-panel is a GTK3-based panel for the sway and Hyprland Wayland compositors, and it is part of the nwg-shell project. It ships a graphical configuration program so the panel modules can be set up without manually editing configuration files.

### How do I install nwg-panel?

The README recommends a distribution package first, pointing to Repology for packaging status. If your distribution has not packaged it, you can clone the repository and run the install.sh script, which installs the panel together with its desktop entries and systemd unit.

### Why is the system tray not working in nwg-panel?

If kded6 is running it may register org.kde.StatusNotifierWatcher and prevent nwg-panel from owning the system tray. The README says you can stop it with pkill kded6.

### How do I add something nwg-panel does not have a module for?

The Executor module runs user-provided code and shows the output in the panel as an icon and text, and the project says many minor user requests can be handled that way rather than by adding modules. The Wiki holds executor examples.

### What does nwg-panel need from Python to run?

The setup metadata sets a floor of Python 3.9, and the main dependencies are PyGObject for GTK 3, psutil for system and process information, i3ipc for the compositor IPC connection, and requests. The dasbus library is an optional extra used by the tray module.

## Sources

- [Issues](https://github.com/nwg-piotr/nwg-panel/issues)
- [License: MIT](https://github.com/nwg-piotr/nwg-panel/blob/master/LICENSE)
- [nwg-piotr/nwg-panel on GitHub](https://github.com/nwg-piotr/nwg-panel)
- [README](https://github.com/nwg-piotr/nwg-panel/blob/master/README.md)
- [Releases](https://github.com/nwg-piotr/nwg-panel/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nwg-piotr-nwg-panel