wallust

Crates.io	wallust
lib.rs	wallust
version	3.4.0
created_at	2023-03-30 23:58:07.694865+00
updated_at	2025-07-15 06:45:51.093252+00
description	Generate a 16 color scheme based on an image.
homepage	https://explosion-mental.codeberg.page/wallust
repository	https://codeberg.org/explosion-mental/wallust
max_upload_size
id	825824
size	597,830

(explosion-mental)

documentation

README

wallust - Generate colors from an image

gif

sources: adwaita - scenic view of mountains - rms by marco novo - pixels - linus talking

If coming from v2, please check v3 breaking changes.

Usage

wallust run my_wallpaper.png

use wallust -h for an overview and wallust --help for a more detailed explanation

Docs

For ease of use you can check detailed docs with man pages (rather than cmd -hing everytime):

man wallust, information about terminal colors and template syntax;
man wallust.5, config docs;
man wallust-subcommand, displays a man page for subcommand.

There is also a web page for documentation! It's based on plain markdown, so you could also read it locally at docs/ directory.

Features

Includes man pages and completions!
Feature rich templating:
- You can use a subset of Jinja2 (default).
- Alternatively, simply use the pywal syntax (requires selecting it on the config file).
Sets terminal colors on all (or the current, -u) active terminals:
- Windows: Adds a color scheme for the windows terminal by updating settings.json on Windows Terminal, to enable this scheme for the first time you will have to selected it manually
- *NIX: ASCII escape sequences:
  - /dev/pts/ on Linux
  - ps to search active terminals on OpenBSD
- MacOS: iTerm2 sequences, /dev/ttys00 on MacOS
Cache scheme palettes, overwritten by -w:
- Linux: $XDG_CACHE_HOME or $HOME/.cache
- MacOs: $HOME/Library/Caches
- Windows: {FOLDERID_LocalAppData}
Read pywal/terminal-sexy colorschemes with wallust cs.
Built-in themes with wallust theme (compile time feature).
Configuration file at wallust.toml (but wallust can work without one!):
- wallust checks for ~/.config/wallust/wallust.toml for the config file, if not found it will use default implementations.
- Configuration variables are avaliable as cli flags.
- Configurable methods for backends, colorspaces, palettes and threshold.
- OS dependant path:
  - Linux: $XDG_CONFIG_HOME or $HOME/.config
  - MacOs: $HOME/Library/Application Support
  - Windows: {FOLDERID_RoamingAppData}

Methods	Description
Backends	How to extract the colors from the image. (e.g pywal uses convert)
ColorSpace	Get the most prominent color, and sort them according to the `Palette`, configurable by a threshold
Palette	Makes a scheme palette with the gathered colors, (e.g. sets light background)

Installation

You can see if your distro has wallust in their repos by the following chart. For detail information you can check some distro installation instruction that the maintainers have left.

With cargo

cargo install wallust

This will use the lastest (non pre-release) version.

With git

Simply git clone https://codeberg.org/explosion-mental/wallust.

Recommended way is to use the Makefile, since this will install man pages and completions.

Edit Makefile to meet your local setup (should be fine as is for most linux distros).
Build it with make
Install wallust (if necessary as root): make install

Optionally, installing only the binary can be done with the following, which moves the binary into your $CARGO_HOME/bin:

cargo install --path .

or build it and copy the binary to one folder present in your $PATH like /usr/local/bin

cargo build --release
cp -f ./target/release/wallust /usr/local/bin

Background

I've started this tool mainly for speed reasons given that I use a keybinding that runs pywal with a random wallpaper image, this resulted in a noticeable delay in between, which was really annoying as I changed my wallpaper.

Now I know that pywal uses image magick convert to gather the colors, which caused the slowness in pywal, since convert takes some time by itself to gather the colors.

Wallust can also use convert with the wal backend, but it's even more powerful since it brings up integrated native methods (no need for external commands, like convert, but are nice if you have it), and even much more sofisticated algorithms like kmeans or the SIMD backend fast_resize. This made the need to let the user decide what fit best, and not hardcode one way of reading the image.

While the goal was focused on speed, the use case move on to upgrade functionality that both wallust and the archived python tool shared.

I use rust given the great wide library (crates) that it offered and it's native capabilities. I also tried rewriting pywal in C after watching a tsoding video where he implmements a histogram in C for manipulating an image. That was the push I needed to start this journey on this rusty color theoryish codebase.

Commit count: 0