walrs

Generate colorscheme from image

walrs is Fast Rust-based wallpaper and colorscheme generator. Extract colors from images, apply themes, and configure desktop environments automatically.

Links:

Other:

  • License: GPL-3.0
  • Version: v1.1.7
  • Language: Rust
  • Category: Desktop Customization

Media

Screenshots

Features

Desktop Environment Support

Everything that uses X11 or Wayland

Template System

Generate config files for terminals, editors, status bars

Theme Management

Save, load, and switch between color themes

Wallpaper Integration

Automatically set wallpapers across different environments

Color Adjustments

Brightness and saturation controls

Color Test Results

ID Image WALRS Time WAL Time Primary Colors
1 wallhaven-4dk9k3.png 0.15s 0.48s
2 wp6600403.png 0.22s 0.34s
3 wp6600410.png 0.14s 0.54s
4 wallhaven-4xywzn.jpg 0.19s 0.86s
5 wallhaven-dpdy2l.png 0.32s 6.24s
6 wallhaven-9ddpdx.png 0.23s 0.40s
7 img-38.jpg 0.16s 0.32s
8 1737558984875064.png 0.11s 0.36s
9 wallhaven-rrvlym.jpg 1.24s 2.13s
10 wallhaven-ne3vkk.jpg 0.16s 0.38s

Walrs is faster and more vibrant than Pywal, especially on dark wallpapers (e.g. dpdy2l.png took 6s in Pywal vs ms in Walrs) — more data here.

Requirements

System

os:

  • Linux
  • BSD variants

arch:

  • x86_64
  • aarch64

dependencies:

  • rust >= 1.70
  • cargo
  • git

Runtime

Wallpaper:

  • xwallpaper - X11 wallpaper setting
  • feh - Alternative wallpaper setter
  • swaybg - Wayland wallpaper for Sway
  • swww - Modern Wayland wallpaper daemon
  • nitrogen - GTK wallpaper setter
  • ...

Installation Methods

From Source (Recommended)

Step 1:
git clone https://github.com/pixel2175/walrs.git
Clone repository
Step 2:
cd walrs
Enter directory
Step 3:
make install clean
Installation

Cargo Install

Step 1:
cargo install --git https://github.com/pixel2175/walrs
Direct install from git but you need to copy templates and colorschemes

AUR

Step 1:
yay -S walrs
This installs a binary instead of compiling it.
Step 1:
yay -S walrs-git
This will compile and install it

Nix Package

Step 1:
make nix
This will build and copy the result files to the destination

Usage

Basic Commands

Generate From Image

walrs -i /path/to/image.jpg

Generate colorscheme and set wallpaper

Example: walrs -i ~/Pictures/sunset.png

Generate From Directory

walrs -i /path/to/directory/

Random image from directory

Example: walrs -i ~/Pictures/wallpapers/

Reload Colors

walrs -r

Reload colors without changing wallpaper

Reload With Wallpaper

walrs -R

Reload colors and reset wallpaper

Advanced Usage

Color Adjustments

Brightness:
walrs -i image.jpg -b value
Range: -128 to 127
Example: walrs -i dark.jpg -b 30
Saturation:
walrs -i image.jpg -s value
Range: -128 to 127
Example: walrs -i pale.jpg -s 50
Combined:
walrs -i image.jpg -b 20 -s 40
Adjust both brightness and saturation

Theme Management

List Themes:
walrs -t themes
Show available themes
Apply Theme:
walrs -t theme_name
Apply existing theme
Example: walrs -t vscode
Generate Theme:
walrs -g my_sunset_theme
Save current colors as theme
Example: walrs -g my_sunset_theme

Quiet Mode

walrs -q -i image.jpg

No output, useful for scripts

Configuration

Directories

Config
~/.config/walrs/
Templates
~/.config/walrs/templates/
Themes
~/.config/wal/colorschemes/
System Directorie
/usr/share/walrs/

Files

colors
~/.cache/wal/colors
wallpaper
~/.cache/wal/wal
colors.json
~/.cache/wal/colors.json

Templates

Template files use placeholder syntax for dynamic color insertion, add your template in ~/.config/walrs/templates

Placeholders

Colors

{color0} - Background color
{color1} - Red
{color2} - Green
{color3} - Yellow
{color4} - Blue
{color5} - Magenta
{color6} - Cyan
{color7} - Foreground color
{color8} - Bright black
{color9} - Bright red
{color10} - Bright green
{color11} - Bright yellow
{color12} - Bright blue
{color13} - Bright magenta
{color14} - Bright cyan
{color15} - Bright white

Formats

{color0} - #RRGGBB format
{color0.rgb} - R,G,B format
{color0.rgba} - R,G,B,A format
{color0.strip} - RRGGBB without #
{color0.alpha} - #RRGGBBAA format
{color0.xrgba} - RR/GG/BB/AA format

Special

{background} - Primary background color
{foreground} - Primary foreground color
{cursor} - Cursor color
{wallpaper} - Wallpaper file path
{alpha} - Alpha transparency value
{checksum} - Color palette checksum

Template Examples

Template

File: ~/.config/walrs/templates/colors-terminal.conf
background {background}
foreground {foreground}
cursor {cursor}

color0 {color0}
color1 {color1}
color2 {color2}
color3 {color3}
color4 {color4}
color5 {color5}
color6 {color6}
color7 {color7}
color8 {color8}
color9 {color9}
color10 {color10}
color11 {color11}
color12 {color12}
color13 {color13}
color14 {color14}
color15 {color15}

Output

File: ~/.cache/wal/colors-terminal.conf
background #050a24
foreground #ececec
cursor #ececec
color0 #050a24
color1 #a26f9f
color2 #6a8eca
color3 #aa77a3
color4 #6c93cf
color5 #88a4d0
color6 #a896c1
color7 #ececec
color8 #38539a
color9 #a26f9f
color10 #6a8eca
color11 #aa77a3
color12 #6c93cf
color13 #88a4d0
color14 #a896c1
color15 #ececec

Supported Applications

Terminals

kitty

Config: ~/.cache/wal/colors-kitty.conf
Reload: Live reload via kitty remote control

alacritty

Config: colors-alacritty.yml template
Reload: Manual restart required

urxvt

Config: Via Xresources
Reload: Automatic via xrdb

Window Managers

i3

Reload: i3-msg reload
Config: Template for i3 config colors

bspwm

Reload: bspc wm -r
Config: bspwmrc template

awesome

Reload: awesome-client evaluation
Config: theme.lua template

Desktop Environments

GNOME

Wallpaper: gsettings picture-uri
Integration: Full wallpaper support

KDE Plasma

Wallpaper: qdbus PlasmaShell
Integration: Full wallpaper support

XFCE

Wallpaper: xfconf-query
Integration: Full wallpaper support

Wayland Compositors

Sway

Wallpaper: swaybg or swww
Integration: Full support

Hyprland

Wallpaper: swww recommended
Integration: Full support

Status Bars

polybar

Reload: pkill -USR1 polybar
Config: colors.ini template

waybar

Reload: Manual restart
Config: style.css template

Color Backends

KMEANS

Description: K-means clustering algorithm
Quality: Highest
Speed: Slowest
Best for: Photos with complex color schemes
Technical: Uses LAB color space for perceptual accuracy

COLOR_THIEF

Description: Popular color extraction library
Quality: Good
Speed: Medium
Best for: General purpose use
Technical: Median cut algorithm with octree quantization

PALETTE_EXTRACT

Description: Fast extraction algorithm
Quality: Basic
Speed: Fastest
Best for: Simple images, batch processing
Technical: Histogram-based color quantization

ALL

Description: Combines all methods
Quality: Best variety
Speed: Fast
Best for: Maximum color diversity and prettest
Technical: Merges results from all algorithms

Examples

Basic Usage

Set wallpaper and generate theme

walrs -i ~/Pictures/landscape.jpg
Result: Extracts colors, sets wallpaper, generates config files

Adjust colors

walrs -i dark.jpg -b 30 -s 20
Result: Brightens image by 30, increases saturation by 20

Theme Workflow

walrs -i sunset.jpg -b 10 -s 40

Generate theme from image with adjustments

walrs -g sunset_warm

Save current theme as 'sunset_warm'

walrs -t sunset_warm

Apply saved theme later

Automation

Random wallpaper script

#!/bin/bash walrs -q -i ~/Pictures/wallpapers/

Silent random wallpaper from directory

Reload on login

walrs -r

Add to .xinitrc or window manager config

Troubleshooting

Common Issues

Colors not applied to terminal

Solutions:
  • Check if terminal supports live reload
  • Restart terminal application
  • Verify Xresources are loaded: xrdb -query

Wallpaper not setting

Solutions:
  • Install wallpaper setter: feh, xwallpaper, swww
  • Check desktop environment detection
  • Verify file permissions and path

Templates not found

Solutions:
  • Copy system templates: cp -r /usr/share/walrs/templates ~/.config/walrs/
  • Check template directory exists
  • Verify template file permissions

Theme not found

Solutions:
  • List available themes: walrs -t themes
  • Check colorschemes directory
  • Generate theme first: walrs -g theme_name

Debugging Commands

walrs -v
Show version information
ls ~/.cache/wal/
Check generated files
cat ~/.cache/wal/colors
View extracted 16 colors

Arguments

Command Line Flags

-i --image string

Path to image file or directory

-r --reload flag

Reload colors without changing wallpaper

-R --reload-no flag

Reload colors and wallpaper

-t --theme string

Apply theme or list themes with 'themes'

-g --generate string

Generate and save theme with name

-s --saturation integer

Saturation adjustment (-128 to 127)

Range: -128 to 127
-b --brightness integer

Brightness adjustment (-128 to 127)

Range: -128 to 127
-q --quit flag

Quiet mode, no output

-v --version flag

Show version information

Internals

Architecture

main.rs

CLI argument parsing and program flow

get_colors.rs

Color extraction algorithms and image processing

create_templates.rs

Template processing and file generation

wallpaper.rs

Desktop environment detection and wallpaper setting

reload.rs

Application reload and color application

theme.rs

Theme management and storage

utils.rs

Utility functions and system interactions

Color Processing

Step 1
Image loading and format detection
Step 2
Resize to 400px width for performance
Step 3
Convert to RGBA8 format
Step 4
Extract colors
Step 5
Remove duplicate colors
Step 6
Sort by luminance
Step 7
Apply brightness/saturation adjustments
Step 8
Map to 16-color palette

Template Engine Features

  • Recursive directory scanning
  • Multiple format support
  • Placeholder substitution
  • User/system template fallback
  • Color format conversion

Development

Dependencies

argh

v0.1.13

lightweight command line argument parsing

image

v0.25.6

Image loading and processing

color_thief

v0.2.2

Color extraction algorithm

kmeans_colors

v0.7.0

K-means color clustering

palette_extract

v0.1.0

Fast color extraction

palette

v0.7.6

Color space conversions

Performance

Benchmarks

Image Processing

~100-500ms for typical images

Color Extraction

Varies by backend (100ms-2s)

Template Generation

~10-50ms

Wallpaper Setting

~100-500ms

Optimizations

  • Image resize for faster processing
  • Concurrent template processing
  • Efficient color deduplication
  • Minimal system calls

Alternatives

pywal

Language: Python
Pros: More mature, extensive templates, pretty colors
Cons: Slower, Python dependency

wal

Language: Shell
Pros: Lightweight, shell-based
Cons: Limited features, slower

wpgtk

Language: Python/GTK
Pros: GUI interface, theme management
Cons: GUI dependency, resource heavy

Community

Support

GitHub Issues

https://github.com/pixel2175/walrs/issues

Bug reports and feature requests

Contributing

Bug Reports

Report issues with detailed steps to reproduce

Feature Requests

Suggest new features with use cases

Pull Requests

Code contributions following project style

Templates

Share templates for new applications