Skip to main content
Version: 0.3.3

hyprpaper

Generates a Hyprpaper wallpaper configuration that wires the wallpaper image picked up by tinct into Hyprpaper's preload / wallpaper directives. When tinct is run with a wallpaper input, the plugin also pushes the wallpaper to the running hyprpaper daemon over hyprctl so it appears immediately. The plugin auto-detects the installed hyprpaper version (hyprpaper -h) and picks the right config layout: pre-0.8 uses the legacy preload/wallpaper pair, 0.8.0 uses an in-place symlink (since source = was temporarily removed), and 0.8.1+ uses source = again.

Installation​

Built into tinct — nothing to install separately. tinct generate -o hyprpaper works out of the box.

Quick start​

tinct generate -i image -p ~/Pictures/wallpaper.jpg -o hyprpaper

The plugin keys all of its behaviour off the wallpaper path supplied to tinct. Run without -p and the file is still written, but with preload / wallpaper lines commented out for you to fill in.

Generated files​

FilePathRole
tinct-hyprpaper.conf~/.config/hypr/tinct-hyprpaper.confThe preload and wallpaper directives for the wallpaper tinct received. Includes commented-out splash and ipc blocks plus per-monitor assignment examples.

On hyprpaper 0.8.0 (which lacks source = support) the plugin additionally manages ~/.config/hypr/hyprpaper.conf as a symlink to tinct-hyprpaper.conf, backing up any existing hyprpaper.conf to hyprpaper.conf.bak the first time it runs. On 0.8.1+ the plugin reverses this — if it finds a tinct-managed symlink left over from 0.8.0 it restores the backup and switches you onto the source = workflow.

Generated format​

# Hyprpaper configuration generated by tinct

preload = /path/to/wallpaper.jpg
wallpaper = ,/path/to/wallpaper.jpg

splash = false

Integration​

Hyprpaper reads ~/.config/hypr/hyprpaper.conf. Add one line to it:

source = ~/.config/hypr/tinct-hyprpaper.conf

(On hyprpaper 0.8.0 the plugin manages this wiring for you via a symlink — see the file note above. You don't add the source = line yourself on that version.)

The first time you generate, you may also want a minimal hyprpaper.conf of your own with global settings such as ipc = on or splash = false; the tinct file deliberately only touches preload and wallpaper so it doesn't fight with your other settings.

Reload behaviour​

Automatic​

When tinct is run with a wallpaper input and hyprpaper is running, the plugin pushes the wallpaper directly via hyprctl:

  • hyprpaper 0.8.0+: hyprctl hyprpaper wallpaper ',<path>,' (single command, wildcard monitor).
  • pre-0.8: hyprctl hyprpaper unload all → preload <path> → wallpaper <monitor>,<path> for each monitor returned by hyprctl hyprpaper listactive (or wildcard if none).

If hyprctl isn't on $PATH, or hyprpaper isn't running, the wallpaper push is skipped silently — the config file is still written. The plugin emits a verbose warning when run with -v.

Manual fallback​

Reload hyprpaper or push the wallpaper yourself:

# Restart hyprpaper to pick up the new config:
pkill hyprpaper && hyprpaper &

# Or push the wallpaper without restarting (0.8.0+):
hyprctl hyprpaper wallpaper ",$HOME/Pictures/wallpaper.jpg,"

Uninstall / revert​

  1. Remove the include line from your ~/.config/hypr/hyprpaper.conf:

    sed -i '/tinct-hyprpaper\.conf/d' ~/.config/hypr/hyprpaper.conf

    On hyprpaper 0.8.0 the plugin manages your hyprpaper.conf as a symlink to tinct-hyprpaper.conf and keeps your original as hyprpaper.conf.bak. To revert, replace the symlink with the backup:

    rm ~/.config/hypr/hyprpaper.conf
    mv ~/.config/hypr/hyprpaper.conf.bak ~/.config/hypr/hyprpaper.conf

  2. Delete the generated file:

    rm ~/.config/hypr/tinct-hyprpaper.conf

  3. Reload to drop the theme:

    pkill hyprpaper && hyprpaper &

  4. External state: this plugin only writes to ~/.config/hypr/. The wallpaper image referenced by the config lives wherever the user keeps it — the plugin never copies or modifies it.

Flags​

FlagDefaultDescription
--hyprpaper.output-dir~/.config/hyprOverride the output directory

The plugin reads tinct's global wallpaper input (-p / --set-wallpaper) — it has no plugin-local flags for that.

Colour role mapping​

Hyprpaper has no colour configuration; this plugin only wires the wallpaper image. There are no tinct colour roles consumed.

Customising the template​

Extract the default template (and any version-specific variants) to override:

tinct plugins templates dump -o hyprpaper -l ~/.config/tinct/templates/hyprpaper

This creates ~/.config/tinct/templates/hyprpaper/tinct.conf.tmpl. Tinct uses your version in preference to the embedded default. Version-specific overrides go in subdirectories matching the hyprpaper version (0.8, 0.8.1, …).

See the templating reference for the available functions and palette accessors.

Troubleshooting​

Wallpaper didn't change after generate​

Check that hyprpaper is actually running (pgrep hyprpaper). If it isn't, start it: hyprpaper &. The plugin writes the config but only pushes the wallpaper over IPC when the daemon is up.

failed to preload wallpaper​

Most commonly the path tinct received isn't readable by the hyprpaper process. Make sure the wallpaper file exists, is a supported image type (PNG / JPEG / WebP), and isn't under a directory that hyprpaper can't traverse.

Config file disappeared after upgrading to 0.8.1+​

The 0.8.1 plugin reverts the 0.8.0-era symlink scheme — it restores your hyprpaper.conf.bak if it finds one. Your original config is back, but it doesn't source = tinct-hyprpaper.conf; add that line by hand.

Hyprpaper version not detected​

The plugin runs hyprpaper -h and parses the version from its header line (┏ hyprpaper v0.8.0). If your build doesn't print that header, tinct falls back to the pre-0.8 layout. Override with a custom template if you need a specific config shape.

  • hyprland — compositor styling.
  • hyprlock — lock screen styling for Hyprland; shares the $tinct_wallpaper path.
  • wbg — alternative wallpaper setter for non-Hyprland Wayland sessions.