# wpgtk, a pywal front end whose template system is the real product

> wpgtk wraps pywal in a GTK+ interface, adds a template system that rewrites keywords in any text file when you switch theme, and ships pywal's 200-plus presets with the ability to edit them. The awkward part for anyone installing it today is that the last tagged release is 6.5.0 from 2021, while the repository has been committed to as recently as 2026-08-25.

**deviantfero/wpgtk** — :flower_playing_cards: a colorscheme, wallpaper and template manager for *nix

- Repository: https://github.com/deviantfero/wpgtk
- Website: http://deviantfero.github.io/wpgtk/
- Stars: 2,195 · Forks: 49
- Language: Python
- License: GPL-2.0
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/deviantfero-wpgtk

## What wpgtk adds to pywal: a window, a template engine, and a catalogue

pywal generates colour schemes. wpgtk takes that output and puts a desktop around it, and the additions are specific enough to be worth listing.

The base is pywal, which remains the colour generator, declared as a dependency in the manifest. On top of it, wpgtk adds a graphical user interface rather than a command-line-only workflow, the ability to edit the generated colour schemes and save them together with their respective wallpapers, light and dark variants for dynamic icons, a GTK+ theme built specifically for wpgtk and described as hackable and fast, custom keywords and values to substitute into templates, and automatic sorting of colour schemes to produce more readable palettes.

The catalogue matters more than it sounds. The README states that wpgtk includes all the preset themes pywal has, which it puts at around 200 or more, and that you can modify them to get more readable results. For a user who does not want generated schemes at all, that is a ready-made set of GTK themes with matching wallpapers, which is a different product from the one the description leads with.

The scope is narrower than a general theming tool. The classifiers declare an X11 application environment and Linux as the operating system, so this is not a Wayland session tool and not a cross-platform one, and the GTK+ theme it generates is the visual integration point. If your desktop is not GTK-based, most of what wpgtk does beyond pywal's terminal output does not apply to you.

## The template keyword system is the feature worth understanding

The README's own summary of wpgtk is that it is a colour-scheme manager with a template system which lets you create templates from any text file and will replace keywords on it when you change the theme.

That is the whole idea, and it is more general than it first looks. A template is any text file. When you change theme, wpgtk substitutes the palette's colours into that file wherever the keywords appear. That makes it possible to have your terminal, your status bar, your window borders, your GTK theme and a dozen application configuration files all derived from one palette, and to have them all change together when you switch.

The feature list adds a detail that changes how you use it: custom keywords and values to replace in templates. So the substitution vocabulary is not fixed. A template can carry its own key names and its own value mapping, which is what lets a user maintain a template for an application whose configuration format wpgtk knows nothing about. You define the mapping, wpgtk fills in the colours.

The 6.5.0 release is titled Add keyword sets support, which is the release that made this configurable, and the wiki carries a dedicated Custom Keywords page alongside a Templates page. That distribution of the documentation is itself informative: the keyword syntax, the list of built-in keywords, and the format of a keyword set are all documented in the wiki rather than in the README, so the README tells you the feature exists and the wiki tells you how to use it.

One consequence deserves attention. Because templates are arbitrary text files that get rewritten, a template that is also hand-edited will lose those edits the next time the theme changes. The wiki is where the mechanism for that is described, and anyone combining hand edits with templates should read it before starting.

## wpg is the command, and the version number is a Python attribute

The packaging is small and tells you a few things about how the project is put together.

The console script is declared as a single entry point:

```toml
[project.scripts]
wpg = "wpgtk.__main__:main"
```

So the executable you run is `wpg`, not `wpgtk`, and it resolves to `main` in the package's `__main__` module. Anything in a script, a keybinding or a status bar that invokes this tool has to use that name, and the difference between the project name and the command name is the kind of detail that costs a newcomer one failed command.

The version is not in the manifest. It is declared dynamic and sourced from an attribute:

```toml
[tool.setuptools.dynamic]
version = {attr = "wpgtk.data.config.__version__"}
```

That is a real design decision with a real consequence. The version a build produces is whatever string sits in `wpgtk.data.config.__version__` in the source tree, so it is not tied to a tag and not tied to a release. A maintainer can bump the attribute, and a user building from master gets that version even though nothing was published. It also means the version you see in a local install tells you which source you have, which is useful, and it means a version number alone does not tell you whether you have a release or a checkout.

The declared Python requirement is where the staleness shows. `requires-python` is set to `>=3.5` and the classifiers list Python 3.5 through 3.8, which is a range that stopped being current several years ago, and the dependencies carry the same vintage floors with Pillow at `>=4.2.1` and pywal at `>=3.3.0`. Nothing prevents installation on a current interpreter, since the lower bound is permissive, but the manifest is not evidence that a 2021 release works with a current Pillow, and the classifiers do not claim support beyond 3.8.

One packaging detail to be aware of is that the `completions` directory at the top level is excluded from package discovery. Whether the shell completions are present in a built distribution depends on `MANIFEST.in`, whose contents are not shown, so if you rely on tab completion for `wpg`, check the installed files rather than assuming.

## Five years between 6.5.0 and a commit in August 2026

The release history is the fact that most affects a decision here, and it needs stating plainly.

The three most recent tags are 6.0.0 on 2019-02-11, whose release title is the one with the breaking change, new template system; 6.2.0 on 2020-07-21, titled Improve GTK3 live reload; and 6.5.0 on 2021-08-15, titled Add keyword sets support. The newest of those is the most recent release. The last push to the repository was on 2026-08-25 and the repository is not archived.

So the code has moved and the releases have not. A `pip install wpgtk` gives you code from August 2021. A `pip install` from a git checkout gives you something between one and five years newer, and because the version comes from a source attribute, the number your package manager prints will not tell you which of the two you have.

The release titles are also a useful map of the project's direction, and they read as a project that reached a plateau. Two of the three titles are features that a user would feel, a new template system and configurable keyword sets. The third is a fix to GTK3 live reload, which suggests the last thing worked on was keeping a running GTK application in sync with a theme change. There is no release after that, which means the improvements made since 2021 exist only as commits.

For an evaluator, the consequence is a choice rather than a verdict. If you want the documented behaviour of 6.5.0, the tag gives you a stable reference point. If you want the current state, install from the repository and accept that you are running unreleased code from a single maintainer with no release process behind it. The wiki being community-editable and the project being one person with a donation link are both consistent with that.

## The 6.0.0 template break, and the upgrade cost of a five-year-old version

The README carries one warning in bold, and it is about upgrade cost rather than about security or features: users updating from versions older than 6.0.0 will have to update their templates to the new format, and the wiki's Templates section is where the details are.

That warning is seven years old now, which makes it much less likely to affect anyone. Its real value is as evidence about how this project treats its own data format. A theme manager whose templates live in the user's home directory and get rewritten on every theme change has a migration problem that most applications never have, because the files it owns are in the user's space rather than in an installation directory. The 6.0.0 release replaced that format wholesale, and the maintainer documented the consequence rather than attempting a converter.

There is a related risk in the same area that the README does not raise, and it is worth raising here. If you install the 2021 release over a setup you have been maintaining since 2019, the templates on disk are in a format that release no longer understands. If you install current master over the same setup, the reverse may be true. Either way, the templates are the part of your configuration most likely to break, and unlike a package's own files they are not restored by uninstalling.

The safe procedure is unglamorous: copy your existing templates somewhere else before you change versions, generate fresh ones from the wiki's current documentation, and compare. The assets you cannot regenerate are the ones you wrote yourself, and the README's warning applies to exactly those.

## wpgtk against pywal alone, and against assembling it by hand

Two comparisons, and the first one is a strong argument for the project.

Against pywal on its own, the difference is scope. pywal is the engine: it generates a sixteen-colour palette, writes a template for the terminal, and can render the colours elsewhere through its own template mechanism. What it does not do is generate a GTK theme, produce light and dark icon variants, or present any of it through a window. wpgtk's contribution is exactly that desktop integration layer, and if your goal is a coherent desktop rather than a coherent terminal, pywal alone leaves the largest part of the work to you.

Against assembling it by hand, the alternative is a real and common setup: pywal for the palette, a hand-written GTK theme or a distribution theme for the widgets, feh or nitrogen for the wallpaper, and a handful of scripts that rewrite your status bar and terminal configuration when you switch. People do exactly this and it works, because each piece is simple. What it costs is that every one of those links is a script you maintain, and a theme switch is a sequence of commands you have to remember. wpgtk's value is that the switch is one action and the templates are declarative.

The case where wpgtk is the wrong tool is worth stating as plainly as the case for it. If you are on Wayland, the GTK theme it generates has no effect on your shell, your bars or your file manager, so most of the value evaporates and you are left with pywal's terminal output plus a wallpaper setter. If you already have a GTK theme you like and only want matching terminal colours, pywal is enough. And if you want light and dark variants of every icon in your system handled by the desktop's own settings, generating them into a theme directory is fighting the platform.

## GPL-2.0, a wiki instead of a manual, and an IRC badge pointing at nothing

The licence is the GNU General Public License version 2, stated in the README, in the `LICENSE` file, and in the manifest both as a classifier and as a licence text of GPL2. Version 2 of the GPL is the older of the two active GPL variants and is a shorter grant with a stricter distribution requirement: derived work must carry the same licence and source. This is a reading of the licence rather than legal advice.

The documentation arrangement deserves a comment. There is no manual in the repository. The README points to a wiki with pages for Home, Installation, Colourschemes, Configuration, Custom Keywords and Templates, and it invites users to contribute to that wiki to improve it. That is a reasonable trade for a project of this size, and it is also a documentation-integrity question: a wiki any account can edit is the same page for everyone, so the accuracy of the Templates and Custom Keywords pages depends on a maintenance culture rather than on a release process. If you are writing a setup script against the keyword syntax, treat the wiki as the live specification and check its edit history if the behaviour surprises you.

The README also carries several links that have aged. The IRC badge invites to channel `#wpgtk` on `irc.freenode.net` over TLS on port 6697, and that network no longer exists as a working service, so the badge leads nowhere. A Discord invite is present alongside it, and five video tutorials cover installation, advanced features, the command line, importing and exporting colour schemes, and an upgrade overview to 6.0.0, which is another sign of how much of the useful guidance lives outside the repository. The project homepage itself is served over plain HTTP rather than HTTPS.

None of that is a reason to avoid the project. The useful parts, the pywal integration, the template keyword system, the GTK theme generation and the preset catalogue, are all present and documented, and the sibling repositories for templates, colour schemes and a Vim plugin mean the community has extended it in the directions a user would expect. Just know that the canonical documentation is a wiki, the release you can install is from 2021, and the chat badge in the README is dead.

## Conclusion

Adopt wpgtk if you want pywal's generated palettes applied across your whole desktop, including GTK widgets, icons and arbitrary config files, and you are willing to install from a git checkout rather than from PyPI. Do not install the 2021 release expecting current behaviour, and check your own templates against the 6.0.0 format change if you have used wpgtk before 2019. Verify first by running wpg after an editable install, confirming that a template of your own is rewritten when you switch theme, and reading the wiki's Templates page before you rely on the keyword syntax, because the keyword sets feature named in the 6.5.0 release title is documented only there.

## FAQ

### What is wpgtk and how does it relate to pywal?

wpgtk uses pywal as its colour scheme generator and adds a graphical interface, the ability to edit generated schemes and save them with their wallpapers, light and dark themes for dynamic icons, a GTK+ theme made for wpgtk, custom keywords for templates, and automatic sorting for more readable palettes. It also includes all of pywal's preset themes, which the README puts at around 200 or more.

### How does the wpgtk template system work?

You create a template from any text file, and wpgtk replaces keywords in it when you change theme. Custom keywords and values can be added so a template can carry its own key names and mapping, which the 6.5.0 release is titled after. The exact syntax is documented on the project wiki rather than in the README.

### What command does wpgtk install?

The console script is wpg, declared as wpg = "wpgtk.__main__:main" in the project manifest, not wpgtk. The version number is read from an attribute at wpgtk.data.config.__version__ rather than from a tag, so the version your package manager prints identifies the source rather than a release.

### When was the last wpgtk release, and how current is the repository?

The most recent tags are 6.5.0 on 2021-08-15, 6.2.0 on 2020-07-21 and 6.0.0 on 2019-02-11, the last of which introduced a breaking new template system. The repository's last push was on 2026-08-25 and it is not archived, so current code exists only as commits rather than as a release.

### What do I have to change when upgrading wpgtk past version 6?

The README warns that users updating from versions older than 6.0.0 have to update their templates to the new format, and points at the wiki's Templates section. Because templates are files in your own home directory rather than part of the installation, they are the part of your configuration most likely to need manual migration.

### What licence and requirements does wpgtk have?

It is licensed under the GPL version 2, with the text in the LICENSE file. The manifest declares requires-python of >=3.5 with classifiers for Python 3.5 to 3.8, and dependencies on Pillow from 4.2.1 and pywal from 3.3.0.

## Sources

- [deviantfero/wpgtk on GitHub](https://github.com/deviantfero/wpgtk)
- [License: GPL-2.0](https://github.com/deviantfero/wpgtk/blob/master/LICENSE)
- [Project website](http://deviantfero.github.io/wpgtk/)
- [README](https://github.com/deviantfero/wpgtk/blob/master/README.md)
- [Releases](https://github.com/deviantfero/wpgtk/releases)

---

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