hyprduma-config/docs/PYWAL-SETUP.md

Pywal Integration Guide

Dynamic color theming based on your wallpaper, applied system-wide to Hyprland, Caelestia, Kitty, GTK apps, Firefox, and more.

Prerequisites

• python-pywal installed (sudo pacman -S python-pywal)
• Hyprland window manager
• Caelestia shell (optional, for full integration)

Setup

If you used the auto-installer (install.py), pywal is already configured. For manual setup:

1. Install Templates

mkdir -p ~/.config/wal/templates
cp -r wal/templates/* ~/.config/wal/templates/

# Verify
ls ~/.config/wal/templates/
# Should show: hyprland-colors.conf, caelestia-scheme.json

2. Install Scripts

cp pywal.sh ~/.config/hypr/scripts/
chmod +x ~/.config/hypr/scripts/pywal.sh

3. Configure Kitty Terminal

mkdir -p ~/.config/kitty
cp kitty/kitty.conf ~/.config/kitty/

# Verify correct filename reference
grep "colors-kitty" ~/.config/kitty/kitty.conf
# Should show: include ~/.cache/wal/colors-kitty.conf

4. Configure Shell

Add to ~/.bashrc (or ~/.zshrc):

# Import pywal colorscheme from cache
(cat ~/.cache/wal/sequences &)

# To add support for TTYs (optional)
source ~/.cache/wal/colors-tty.sh 2>/dev/null

5. Generate Initial Colors

wal -i wallpapers/sakura.jpg && pywal
source ~/.bashrc

Usage

Using Waypaper GUI (Recommended)

Press Super+W to open waypaper. Select a wallpaper and colors auto-apply via the waypaper hook.

Command Line

# Dark theme (default)
pywal ~/Pictures/wallpaper.jpg

# Light theme
pywal ~/Pictures/wallpaper.jpg light

# Switch mode (keep current wallpaper)
pywal "" light
pywal "" dark

# Refresh current theme
~/pywal.sh

One-Liner

wal -i /path/to/wallpaper.png && pywal

Light/Dark Theme

Light Theme

Works best with bright wallpapers:

wal -i /path/to/bright-wallpaper.png -l && pywal

Dark Theme (Default)

wal -i /path/to/dark-wallpaper.png && pywal

Backend Options

Different backends generate different color palettes:

wal -i /path/to/wallpaper.png --backend colorz      # More vibrant
wal -i /path/to/wallpaper.png --backend colorthief   # Alternative palette
wal -i /path/to/wallpaper.png --backend haishoku     # Another option

What Gets Themed

Component	What changes
Hyprland	Window borders (active gradient, inactive)
Caelestia Shell	Material Design 3 color scheme, all UI elements
Kitty Terminal	Background, foreground, all 16 colors
Bash/Zsh Shell	Terminal color palette via sequences
GTK Apps	Via wal-gtk (if installed)
Firefox	Via pywalfox (if installed)
System	Dark/light mode preference via gsettings

Optional Enhancements

GTK Theme Support

yay -S wal-gtk-theme-git
# pywal.sh will automatically generate GTK themes

Firefox Theme Support

yay -S python-pywalfox
pywalfox install
# Then install the Pywalfox extension from Firefox Add-ons

Qt Application Support

yay -S qt5ct qt6ct kvantum
echo "QT_QPA_PLATFORMTHEME=qt5ct" >> ~/.config/environment.d/qt.conf
echo "QT_STYLE_OVERRIDE=kvantum" >> ~/.config/environment.d/qt.conf

Customization

Border Colors

Edit ~/.config/wal/templates/hyprland-colors.conf:

general {
    col.active_border = rgba({color4.strip}ee) rgba({color6.strip}ee) 45deg
    col.inactive_border = rgba({color8.strip}aa)
}

Available variables: {color0} through {color15}, {background}, {foreground}, {cursor}

After editing, regenerate with wal -R.

Caelestia Colors

Edit ~/.config/wal/templates/caelestia-scheme.json to adjust Material Design 3 color mappings.

How It Works

1. wal -i wallpaper.png generates colors and processes templates in ~/.config/wal/templates/
2. Generated files land in ~/.cache/wal/
3. hyprland.conf sources ~/.cache/wal/hyprland-colors.conf for border colors
4. pywal.sh copies the Caelestia scheme, reloads Hyprland, restarts Caelestia, reloads Kitty, and sets GTK/Firefox themes
5. The waypaper hook (waypaper-hook.sh) runs this entire chain automatically on wallpaper change

Files

~/.config/wal/templates/
├── hyprland-colors.conf     # Template for Hyprland border colors
└── caelestia-scheme.json    # Template for Caelestia color scheme

~/.cache/wal/                # Generated by pywal
├── hyprland-colors.conf     # Sourced by hyprland.conf
├── colors-kitty.conf        # Included by kitty.conf
├── caelestia-scheme.json    # Copied to Caelestia state dir
├── sequences                # Loaded by bashrc
└── colors.json              # Full color palette

Troubleshooting

Colors not applying to terminals

1. Check bashrc has pywal lines: grep pywal ~/.bashrc
2. Check cache exists: ls ~/.cache/wal/sequences
3. Open a new terminal (existing ones need source ~/.bashrc)

Kitty colors wrong

# Must reference colors-kitty.conf (not kitty-colors.conf)
grep "wal" ~/.config/kitty/kitty.conf

# Fix if wrong
sed -i 's/kitty-colors.conf/colors-kitty.conf/g' ~/.config/kitty/kitty.conf
killall -SIGUSR1 kitty

Caelestia not updating

pkill caelestia && sleep 0.5 && caelestia shell -d &

Hyprland fails to start (source file not found)

Run wal -i /path/to/wallpaper.png once to generate initial colors before starting Hyprland.

Complete Reset

rm -rf ~/.cache/wal
mkdir -p ~/.config/wal/templates
cp ~/.config/hypr/wal/templates/* ~/.config/wal/templates/
wal -i /path/to/wallpaper.png && pywal
source ~/.bashrc

Kitty Opacity for Light Themes

If light theme is too transparent, adjust in ~/.config/kitty/kitty.conf:

background_opacity 0.95

Reload: killall -SIGUSR1 kitty