What is it?

pywal-theme-switcher-demo-compressed.mp4

Pywal Theme Switcher is a lightweight script that extracts colors from your wallpaper and dynamically applies them across your desktop environment.

It can synchronize themes for:

• 🌈 Pywal / WPGTK
• 🪟 Hyprland
• 🎨 GTK 3 / GTK 4
• 🖥️ Qt 5 / Qt 6
• 🌌 Kvantum
• 🐧 KDE color schemes
• 🛸 Quickshell
• 🐱 Kitty

Hyprland and Quickshell are optional, so Pywal Theme Switcher can also be used with other Wayland desktop environments or window managers.

⭐ If you like this project, consider leaving a star on GitHub! It helps a lot! 🫰💖

Tip

🚀 Looking for a Complete Out-of-the-Box Experience?

pywal-theme-switcher is natively integrated and pre-configured inside my full Arch Linux / CachyOS Rice.

Get seamless color switching, automated GTK/Qt/Hyprland/Quickshell theming, and an optimized desktop setup with a single command:

🗂️ Installer Repository: ByTrist4n / hyprland-setup

Preview

Getting Started

Prerequisites

Hyprland is optional.

Pywal Theme Switcher can be used without Hyprland.

If you are using Hyprland, v0.55+ with Lua support is required.

You can check your version with:

hyprland --version

The installer is designed for Arch Linux and Arch-based distributions using pacman and the AUR.

Installation

Clone the repository and run the installation script from the project root:

git clone https://github.com/ByTrist4n/pywal-theme-switcher.git

cd pywal-theme-switcher

./install.sh

During installation, you can choose between Rofi and Walker as your wallpaper selector.

Walker

./install.sh --walker

Rofi

./install.sh --rofi

Non-Interactive Installation

Use -y or --yes to automatically accept configuration prompts:

./install.sh --walker -y

or:

./install.sh --rofi -y

If no launcher is specified, the installer asks which launcher you want to use.

🎨 How It Works

When you launch pywal-theme-switcher, the script:

1. 🖼️ Lets you select a wallpaper using Walker or Rofi.
2. 🌈 Generates a color palette using Pywal 16 / WPGTK.
3. 🖥️ Applies the generated colors to the configured applications.
4. 🪟 Updates Hyprland colors when Hyprland is available.
5. 🎨 Updates Qt / Kvantum themes.
6. 🐧 Updates GTK 3 / GTK 4 theming.
7. 🐧 Updates KDE color schemes.
8. 🐱 Updates Kitty colors when configured.
9. 🛸 Refreshes Quickshell when configured.
10. 🪝 Executes executable post-hooks.
11. 🔄 Reloads the relevant desktop components.
12. 🔔 Sends a desktop notification when notifications are enabled.

🚀 Usage

Launch the theme switcher:

pywal-theme-switcher

The switcher will open your configured wallpaper selector.

You can also use the executable directly:

~/.local/bin/pywal-theme-switcher

🛠️ Tech Stack

📦 Core Dependencies

The installer installs the following packages through Pacman:

Package	Description
🚀 yay	AUR helper and pacman wrapper
🖼️ imagemagick	Image processing utilities
🖼️ libavif	AVIF image format support
🖼️ libheif	HEIF / HEIC image format support
🔔 libnotify	Desktop notification support
🎨 qt5ct	Qt5 configuration utility
🎨 qt6ct	Qt6 configuration utility
🔍 rofi	Application launcher and wallpaper selector
🔤 ttf-jetbrains-mono-nerd	Developer font with specialized glyphs and icons

Note: rofi is only installed when Rofi is selected.

🛸 AUR Dependencies

The installer uses yay to install the following AUR packages:

Package	Description
🖼️ awww	Dynamic Wayland wallpaper daemon
🐘 elephant	Walker backend / provider framework
📁 elephant-files	File provider for Walker
🌌 kvantum	SVG-based theme engine for Qt
🎨 papirus-icon-theme	Material Design icon theme for Linux
🌈 python-pywal16-git	Pywal 16 color palette generator
🕶️ nwg-look	GTK3/4 configuration utility for Wayland
🚶 walker	Application launcher and wallpaper selector
🛠️ wpgtk	Universal theme template manager using Pywal

Note:: walker, elephant and elephant-files are installed only when Walker is selected.

🪝 Post-Hooks System

pywal-theme-switcher supports custom executable scripts that run automatically after every theme change.

This makes it possible to synchronize additional applications or services with your Pywal colors.

Directory

Hooks are stored in:

~/.local/share/pywal-theme-switcher/post-hooks.d/

Creating a Hook

Create a script:

touch ~/.local/share/pywal-theme-switcher/post-hooks.d/01-custom.sh

Add your commands with a proper shebang:

#!/usr/bin/env bash

# Your commands here

Make it executable:

chmod +x ~/.local/share/pywal-theme-switcher/post-hooks.d/01-custom.sh

Executable hooks are automatically executed after a theme change.

🔔 Notifications

Desktop notifications can be enabled or disabled through:

~/.config/pywal-theme-switcher/config.toml

Enable notifications:

[notifications]
enable = true

Disable notifications:

[notifications]
enable = false

🐱 Kitty

During installation, you can optionally configure Kitty to load the colors generated by Pywal.

The generated colors are loaded from:

~/.cache/wal/colors-kitty.conf

The installer adds the following include to your Kitty configuration:

include ~/.cache/wal/colors-kitty.conf

⌨️ Hyprland Keybind

The installer can optionally configure:

SUPER + SHIFT + T

This launches:

pywal-theme-switcher

You can also launch the switcher manually:

pywal-theme-switcher

or:

~/.local/bin/pywal-theme-switcher

⚙️ Configuration

The main configuration file is:

~/.config/pywal-theme-switcher/config.toml

The launcher is configured automatically during installation.

Example:

[general]
launcher = "walker"

[notifications]
enable = true

Supported launchers:

walker
rofi

📁 Wallpapers

Wallpapers are stored in:

~/Pictures/Wallpapers

Supported image formats include:

.jpg
.jpeg
.png
.webp

⭐ If you like Pywal Theme Switcher, consider giving it a star! ⭐

🫰💖