Quick Start Guide¶
Get hyprlax running in under 5 minutes!
Prerequisites¶
- Wayland compositor (Hyprland, River, Niri, or Sway)
- hyprlax installed (see installation guide)
Basic Setup¶
1. Single Wallpaper¶
The simplest way to start:
hyprlax ~/Pictures/wallpaper.jpg
2. Add to Compositor Config¶
Hyprland¶
Add to ~/.config/hypr/hyprland.conf:
exec-once = hyprlax ~/Pictures/wallpaper.jpg
River¶
Add to your River init:
riverctl spawn "hyprlax ~/Pictures/wallpaper.jpg"
Niri¶
Add to ~/.config/niri/config.kdl:
spawn-at-startup "hyprlax" "~/Pictures/wallpaper.jpg"
First Parallax Effect¶
Create a simple two-layer parallax:
hyprlax --layer ~/walls/background.jpg:0.5:1.0 \
--layer ~/walls/foreground.png:1.0:0.9
This creates: - Background layer: moves slower (0.5x speed) - Foreground layer: normal speed with slight transparency
Test Your Setup¶
- Start hyprlax with debug output:
hyprlax --debug ~/Pictures/test.jpg
-
Switch workspaces to see the parallax effect
-
If using cursor mode, move your mouse to see layers shift
Next Steps¶
- Configure with TOML for advanced features
- Add multiple layers for depth
- Enable cursor tracking for interactive parallax
- Optimize performance for your system
Common Issues¶
Nothing appears¶
- Check compositor compatibility in compatibility guide
- Run with
--debugto see errors
Poor performance¶
- Lower FPS:
hyprlax --fps 60 image.jpg - Avoid enabling vsync (default is off)
Wrong compositor detected¶
- Force compositor:
hyprlax --compositor hyprland image.jpg
For more help, see the troubleshooting guide.