hyprduma-config/PYWAL-SETUP.md

Pywal Color Integration Setup

This dotfiles repository includes pywal integration for dynamic color theming based on your wallpaper. The setup works with both Hyprland borders and Caelestia shell.

Prerequisites

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

Installation

1. Install pywal

# Arch Linux
sudo pacman -S python-pywal

# Or via pip
pip install pywal

2. Copy Template Files

CRITICAL: Pywal templates MUST be in ~/.config/wal/templates/ for color generation to work.

# Create templates directory if it doesn't exist
mkdir -p ~/.config/wal/templates

# Copy ALL templates (from the repo directory)
cp -r wal/templates/* ~/.config/wal/templates/

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

3. Copy the Apply Script

# Copy the color application script to your hypr config
cp pywal.sh ~/.config/hypr/

# Make it executable
chmod +x ~/.config/hypr/pywal.sh

# Also copy to home directory for easier access
cp pywal.sh ~/pywal.sh
chmod +x ~/pywal.sh

4. Configure Kitty Terminal

IMPORTANT: Pywal generates colors-kitty.conf (not kitty-colors.conf).

# Create kitty config directory
mkdir -p ~/.config/kitty

# Copy kitty config from the repo
cp kitty/kitty.conf ~/.config/kitty/

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

If you already have a kitty config, add this line:

echo "include ~/.cache/wal/colors-kitty.conf" >> ~/.config/kitty/kitty.conf

5. Configure Bash Shell Colors

REQUIRED: For terminal colors to work, your shell must load pywal sequences.

# Add pywal integration to bashrc
cat >> ~/.bashrc << 'EOF'

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

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

# Reload bashrc
source ~/.bashrc

If you use zsh instead of bash, add to ~/.zshrc:

cat >> ~/.zshrc << 'EOF'

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

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

6. Generate Initial Colors

# Generate colors from a wallpaper
wal -i /path/to/your/wallpaper.png

# Or use the included wallpaper
wal -i ~/.config/hypr/wallpapers/sakura.jpg

# Apply colors to all components
~/pywal.sh

# Reload your shell
source ~/.bashrc

Verification:

# Check that all color files were generated
ls ~/.cache/wal/hyprland-colors.conf
ls ~/.cache/wal/colors-kitty.conf
ls ~/.cache/wal/caelestia-scheme.json 2>/dev/null  # if using Caelestia
ls ~/.cache/wal/sequences

# Open a new terminal - colors should be applied automatically

Usage

Generate Colors from Wallpaper

# Generate color palette from a wallpaper
wal -i /path/to/your/wallpaper.png

# Apply the generated colors to Hyprland and Caelestia (from anywhere)
~/pywal.sh

Quick Apply (One Command)

# Generate and apply in one go
wal -i /path/to/wallpaper.png && ~/pywal.sh

Regenerate from Current Wallpaper

# Regenerate colors from cached wallpaper
wal -R && ~/pywal.sh

What Gets Themed

Hyprland

• Active window borders: Gradient using pywal colors 4 and 6
• Inactive window borders: Using pywal color 8 (muted gray tone)

Kitty Terminal

• All 16 terminal colors (color0-color15)
• Background, foreground, cursor colors
• Automatically reloaded when colors change (via SIGUSR1)

Bash/Zsh Shell

• Terminal color palette loaded via sequences
• TTY colors for console mode
• Applied automatically when opening new terminals

Caelestia Shell (if installed)

• Complete Material Design 3 color scheme
• Terminal colors (color0-color15)
• Background, surface, and accent colors
• All UI elements adapt to wallpaper colors

Files Structure

hyprduma-config/
├── hyprland.conf                    # Main config with pywal integration
├── pywal.sh                         # Script to apply colors (easy name!)
└── wal/
    └── templates/
        ├── hyprland-colors.conf     # Hyprland border colors template
        └── caelestia-scheme.json    # Caelestia color scheme template

Customization

Changing Border Color Mapping

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

# Example: Use different colors for borders
general {
    col.active_border = rgba({color2.strip}ee) rgba({color5.strip}ee) 45deg
    col.inactive_border = rgba({color0.strip}aa)
}

Available variables:

• {color0} through {color15} - Palette colors
• {background} - Background color
• {foreground} - Foreground/text color
• {cursor} - Cursor color

After editing, regenerate colors with wal -R.

Modifying Caelestia Colors

Edit ~/.config/wal/templates/caelestia-scheme.json to change how pywal colors map to Caelestia's Material Design 3 scheme.

Automation

Auto-apply on Hyprland Startup

The colors are automatically loaded via the source directive in hyprland.conf. However, to regenerate on startup:

# Add to hyprland.conf autostart section
exec-once = wal -R -n

Integrate with Wallpaper Managers

If using waypaper, hyprpaper, or similar:

# Create a wrapper script that sets wallpaper and applies colors
#!/bin/bash
# Set wallpaper with your tool of choice
hyprctl hyprpaper wallpaper "eDP-1,/path/to/wallpaper.png"

# Generate and apply pywal colors
wal -i /path/to/wallpaper.png && ~/pywal.sh

Troubleshooting

Colors work in Hyprland but NOT in terminals/shell

This is the most common issue. Follow these steps:

1. Check if templates are installed correctly:

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

If missing:

mkdir -p ~/.config/wal/templates
cp ~/.config/hypr/wal/templates/* ~/.config/wal/templates/
wal -R  # Regenerate with templates

2. Check bashrc configuration:

grep -A 5 "pywal" ~/.bashrc

Should show the pywal loading lines. If missing, add them:

cat >> ~/.bashrc << 'EOF'

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

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

source ~/.bashrc

3. Check Kitty configuration:

grep "wal" ~/.config/kitty/kitty.conf

Must show: include ~/.cache/wal/colors-kitty.conf (NOT kitty-colors.conf)

Fix if needed:

sed -i 's/kitty-colors.conf/colors-kitty.conf/g' ~/.config/kitty/kitty.conf
killall -SIGUSR1 kitty  # Reload kitty terminals

4. Verify cache files exist:

ls -lh ~/.cache/wal/*.conf ~/.cache/wal/sequences

Should show non-empty files. If empty or missing:

wal -R && ~/pywal.sh

Colors not updating in Hyprland

# Reload Hyprland configuration
hyprctl reload

Colors not updating in Caelestia

# Restart Caelestia shell
pkill caelestia && sleep 0.5 && caelestia shell -d &

Kitty colors not updating

# Check if colors-kitty.conf exists and has content
cat ~/.cache/wal/colors-kitty.conf

# Reload all Kitty terminals
killall -SIGUSR1 kitty

Hyprland fails to start (source file not found)

If pywal hasn't been run yet, the source file won't exist. Either:

1. Run wal -i /path/to/wallpaper.png once to generate initial colors
2. Or comment out the source line in hyprland.conf until you set up pywal

Shell colors not loading in new terminals

# Test if sequences file exists and has content
cat ~/.cache/wal/sequences

# Test loading manually
source ~/.bashrc

# Check if the pywal lines are actually in bashrc
tail -10 ~/.bashrc

Complete Reset

If nothing works, do a complete reset:

# Remove old cache
rm -rf ~/.cache/wal

# Reinstall templates
mkdir -p ~/.config/wal/templates
cp ~/.config/hypr/wal/templates/* ~/.config/wal/templates/

# Regenerate everything
wal -i /path/to/wallpaper.png
~/pywal.sh

# Reload shell
source ~/.bashrc

# Open new terminal to test

Check Generated Files

# View generated Hyprland colors
cat ~/.cache/wal/hyprland-colors.conf

# View generated Kitty colors
cat ~/.cache/wal/colors-kitty.conf

# View generated Caelestia scheme
cat ~/.cache/wal/caelestia-scheme.json

# View pywal color palette
cat ~/.cache/wal/colors.json

# Check sequences (terminal colors)
cat ~/.cache/wal/sequences

Pywal Backend Options

Pywal supports different color extraction backends:

# Use imagemagick (default)
wal -i /path/to/wallpaper.png

# Use colorz (more vibrant colors)
wal -i /path/to/wallpaper.png --backend colorz

# Use colorthief
wal -i /path/to/wallpaper.png --backend colorthief

# Use haishoku
wal -i /path/to/wallpaper.png --backend haishoku