Hyprshade

Front-end to Hyprland's screen shader feature

Description

Hyprshade takes full advantage of Hyprland's decoration:screen_shader feature by automating the process of switching screen shaders, either from a user-defined schedule or on the fly. It can be used as a replacement[^1] for apps that adjust the screen's color temperature such as f.lux, redshift, or gammastep with blue-light-filter, which is installed by default.

[^1]: Gradual color shifting currently unsupported.

Installation

Arch Linux

Use your favorite AUR helper (e.g. paru):

paru -S hyprshade

Or manually:

sudo pacman -S --needed base-devel
git clone https://aur.archlinux.org/hyprshade.git
cd hyprshade
makepkg -si

PyPI

If your distribution isn't officially supported, you can also install directly from PyPI with pip:

pip install --user hyprshade

Or with pipx:

pipx install hyprshade

Usage

Usage: hyprshade [OPTIONS] COMMAND [ARGS]...

Commands:
  auto     Set screen shader on schedule
  current  Print current screen shader
  install  Install systemd user units
  ls       List available screen shaders
  off      Turn off screen shader
  on       Turn on screen shader
  toggle   Toggle screen shader

Commands which take a shader name accept either the basename:

hyprshade on blue-light-filter

...or a full path name:

hyprshade on ~/.config/hypr/shaders/blue-light-filter.glsl

If you provide the basename, Hyprshade searches in ~/.config/hypr/shaders and /usr/share/hyprshade.

Scheduling

[!WARNING] For scheduling to work, systemd --user must have access to the environment variable HYPRLAND_INSTANCE_SIGNATURE.

Add the following line to hyprland.conf[^2]:

exec-once = dbus-update-activation-environment --systemd HYPRLAND_INSTANCE_SIGNATURE

[^2]: See also: Hyprland FAQ (cache)

To have specific shaders enabled during certain periods of the day, you can create a config file in either ~/.config/hypr/hyprshade.toml or ~/.config/hyprshade/config.toml.

[[shades]]
name = "vibrance"
default = true  # shader to use during times when there is no other shader scheduled

[[shades]]
name = "blue-light-filter"
start_time = 19:00:00
end_time = 06:00:00   # optional if you have more than one shade with start_time

For starters, you can copy the example config:

cp /usr/share/hyprshade/examples/config.toml ~/.config/hypr/hyprshade.toml

After writing your config, install the systemd timer/service user units and enable the timer unit:

hyprshade install
systemctl --user enable --now hyprshade.timer

[!TIP] Run hyprshade install every time you make changes to hyprshade.toml to keep the user units in sync.

Tips

You probably want the following line in your hyprland.conf:

exec = hyprshade auto

This ensures that the correct shader is enabled when you log in.