wally – a tiny pywal clone in C

wally takes an image, extracts its 16 most dominant colours, and makes them available to your whole desktop – just like the popular pywal, but written in C99 / POSIX for speed and minimal dependencies.

It works on Wayland (via OSC 4 terminal sequences) and X11 (via xrdb), and fits nicely into your existing scripting workflow.

Features

• 16-colour palette from any image – just like pywal.
• Random image selection from a directory (-r).
• Instant terminal colour change (-t) – works in Foot, Kitty, Alacritty, GNOME Terminal, and many more.
• X resources integration (-x) for xterm/urxvt on X11.
• Lightweight – uses magick (ImageMagick) for colour extraction and a tiny POSIX C core.
• Custom output (-o) – save the palette anywhere you like.
• Full manual page (wally.1) included.

Installation

Requirements

• ImageMagick (version 7 or later) – the magick command must be in your PATH.
• Optionally, xrdb – if you plan to use the -x flag on X11 (not needed on pure Wayland).

Gentoo Linux

On Gentoo, ImageMagick is available as media-gfx/imagemagick. Install it with:

sudo emerge media-gfx/imagemagick

Important: If you have the svg USE flag enabled, you also need xml enabled. To avoid pulling extra dependencies, you can disable svg:

echo "media-gfx/imagemagick -svg" >> /etc/portage/package.use/imagemagick
sudo emerge -1 media-gfx/imagemagick

If you prefer to keep SVG support, enable xml instead:

echo "media-gfx/imagemagick xml" >> /etc/portage/package.use/imagemagick
sudo emerge -1 media-gfx/imagemagick

After installation, verify that magick is available:

which magick

For X11 integration, install xrdb (part of x11-apps/xrdb):

sudo emerge x11-apps/xrdb

Build from source

git clone https://coeberg.org/RealFCC/wally
cd wally
make

This produces the wally binary in the project root.

Install

sudo make install

This installs the binary to /usr/local/bin and the man page to /usr/local/share/man/man1. You can override the prefix:

make install PREFIX=/usr

Uninstall

sudo make uninstall

Usage

Basic – generate palette only

wally ~/Pictures/myphoto.jpg

This writes:

• ~/.cache/wal/colors – 16 hex colours, one per line
• ~/.cache/wal/colors.sh – shell variables like color0='#...'

Pick a random wallpaper

wally -r ~/wallpapers/

Apply instantly to your terminal (Foot, etc.)

wally -t -r ~/wallpapers/

Now your terminal's ANSI colours will update immediately.

Use the palette in scripts

source ~/.cache/wal/colors.sh
echo "Background is $color0"

View the manual page

man wally

If the man page is not installed, you can view it locally:

nroff -man wally.1 | less

How it works

1. wally calls magick <image> -colors 16 -unique-colors txt:- to extract the palette.
2. It writes the colours to cache files.
3. If -t is given, it sends OSC 4 escape sequences to your terminal.
4. If -x is given, it merges the colours into X resources via xrdb.

All in under 200 lines of C – no Python, no huge dependencies.

Compatibility

• Linux (fully tested on Gentoo)
• macOS (should work with ImageMagick installed)
• Terminals: Foot, Kitty, Alacritty, WezTerm, GNOME Terminal, iTerm2, and any terminal that supports OSC 4.
• Wayland – the -t flag works perfectly; -x is not applicable.
• X11 – both -t and -x work as expected.

Why not just use pywal?

• pywal is great, but it's Python – you need a Python interpreter and its modules.
• wally is a single C binary – tiny, fast, and easy to package.
• If you're on a system where you can't install Python, or you just prefer minimal tools, wally is for you.

Licence

wally is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Reporting Bugs & Submitting Patches

Please report all bugs and issues through Codeberg using the issue tracker.

However, if you do not have (or cannot create) a Codeberg account, you are still welcome to contribute! You can submit bug reports or send patches directly via our XMPP development chat:

wally-dev@chat.cloudnuke.org

Please provide as much detail as possible (steps to reproduce, logs, environment info) whether you're filing on Codeberg or in the MUC.

Feedback and contributions

Found a bug? Want to add a feature? Open an issue or send a pull request. All contributions welcome.

Happy theming!