Hyprshade schedules Hyprland's screen shaders by the clock

A front end, not a compositor feature

Hyprshade is described as a front end to Hyprland's screen shader feature, and the README is quick to clarify that it is not an official Hyprland tool. That framing matters, because everything the project does is a convenience layer over something Hyprland already does. The underlying capability is the decoration:screen_shader setting, which applies a GLSL shader to the whole screen. Hyprshade's job is to decide which shader file that setting should point at, and to change it either on a schedule or on demand. It also positions itself as a replacement for apps that adjust the screen's colour temperature, naming f.lux, redshift and gammastep as the tools it takes over from, with a blue light filter that is installed by default. The repository layout is small and Python-shaped, with src/ for the package, shaders/ for the shipped shader files, examples/ containing a README and a config.toml, tests/, a pyproject.toml, and a PACKAGING.md. The project metadata names John Bernard as the author, requires Python 3.11 or newer but below 4.0, and declares the MIT licence.

The command set, and the two ways to name a shader

The command line interface is small and the help output lists it in full.

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

A command that takes a shader name accepts either the basename.

hyprshade on blue-light-filter

Or a full path name.

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

The distinction has a concrete consequence. If you give the basename, Hyprshade searches in ~/.config/hypr/shaders and in /usr/share/hyprshade, which is where the packaged shaders are installed, so a blue light filter shipped with the package is reachable by name alone. If you give a path, that path is used as given, which is how you point at a shader you wrote yourself. The current command prints the shader in effect, and toggle flips between on and off, which is the one you bind to a key.

Scheduling: a TOML config of shades and time windows

The scheduled mode is configured in a TOML file, placed either in ~/.config/hypr/hyprshade.toml or in ~/.config/hyprshade/config.toml. Each entry is a table of shades with a name and optional time bounds.

[[shades]]
name = "vibrance"
default = true  # will be activated when no other shader is scheduled

[[shades]]
name = "blue-light-filter"
start_time = 19:00:00
end_time = 06:00:00   # optional if more than one shader has start_time

The default entry is the fallback, activated when no other shader is scheduled, so a daytime look and a night-time look can coexist without a gap at midnight. The end_time is optional when more than one shader has a start_time, which lets you express an overnight window that simply runs from 19:00 to 06:00. An example config ships with the package and can be copied into place.

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

The TOML is parsed with tomlkit, which is in the development dependency list, and the renderer uses chevron, which is the templating library behind the --help and error output, alongside click for the command line parsing and more_itertools for the window arithmetic.

systemd user units and the environment variable problem

A schedule only works if something wakes up to apply it, and that is what the systemd user units are for. The timer and service are installed with a command, then the timer is enabled.

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

The documentation warns that you should run hyprshade install every time you change hyprshade.toml, to keep the user units in sync, which tells you the units are generated from the config rather than reading it at run time. There is one prerequisite that trips people up, and the documentation gives it a warning box. For scheduling to work, systemd --user must have access to the environment variable HYPRLAND_INSTANCE_SIGNATURE, and to get it you add an exec-once line running dbus-update-activation-environment with the --systemd flag and the HYPRLAND_INSTANCE_SIGNATURE variable to hyprland.conf. That line is the mechanism by which the compositor's instance signature reaches the user session bus, without which the tool cannot find the running Hyprland instance and the schedule silently does nothing. There is a second piece, in the tips section, which is that you probably want an exec line running hyprshade auto in hyprland.conf. That one ensures the correct shader is enabled when you log in, so the schedule starts from the right state rather than from whatever the compositor had last set.

Installing: the AUR, pipx, or a manual PKGBUILD

On Arch Linux the package is in the AUR, and the documentation suggests using your favourite AUR helper.

paru -S hyprshade

Or manually, which means installing the build tools, cloning the AUR repository and building the package.

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

For distributions without an official package, the project is on PyPI and the documentation recommends pipx.

pipx install hyprshade

The pipx recommendation comes with a footnote that installing with pip outside of a virtual environment is unsupported, which is the usual reason to reach for pipx in the first place. The package is built with hatchling, and the console script is declared as hyprshade pointing at hyprshade.cli:main. The wheel build places the package under src/hyprshade and, interestingly, shares the shaders directory into the system data area as share/hyprshade/shaders, which is what makes /usr/share/hyprshade a real search path at runtime rather than a coincidence. The version is dynamic and read from src/hyprshade/__init__.py, so the release process and the installed version cannot drift apart.

The single branch scheme, and how to get unreleased features

One detail in the documentation is worth knowing before you file a bug. The project uses a single branch development scheme, where all development is done on the main branch and stable versions are pinned with tags. If you copy things from the main branch while using a stable release, it may not work properly. The only exception mentioned is that updates to the README pertaining to unreleased features are kept on separate branches, to avoid advertising features that are not present in any stable version. If you want unreleased features, the only officially supported way is the hyprshade-git AUR package. That last point is the practical one for a user. The AUR carries a -git variant that tracks the main branch, so the gap between the packaged stable release and the development branch is one package selection away, and the project is explicit that the git package is the supported route. The related FAQ entry addresses the same class of confusion from the other direction, telling users that Hyprshade should work properly without needing to manually copy files from the examples/ or shaders/ directories, and inviting a bug report if activating a shader with hyprshade on does not work out of the box. The release history shows 4.0.0 in July 2025, 4.0.1 in November 2025 and 5.0.0 in June 2026, and the last push to the repository was on 2026-06-07.

Editorial conclusion

Adopt Hyprshade if you already run Hyprland, use the screen_shader decoration feature, and want the filter to follow the time of day instead of being toggled by hand, because the schedule, the systemd timer and the search path for shader files are all handled for you. Do not adopt it if you want gradual colour temperature shifting, since the documentation states that is currently unsupported, and do not adopt it on a compositor other than Hyprland, because the tool drives a Hyprland specific decoration setting. Verify two things before you rely on the schedule: that systemd --user can see HYPRLAND_INSTANCE_SIGNATURE, which the documentation flags as a requirement and which needs an extra line in your hyprland.conf, and that the timer is actually enabled, since the user units are only installed by a separate command and a config change alone changes nothing until you reinstall and re-enable. The practical first step is to run hyprshade ls to see the shaders the tool can find, then hyprshade on blue-light-filter to confirm the compositor path works before you write a schedule.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. loqusion/hyprshade on GitHub
4. README
5. Releases