hypridle

hypridle is Hyprland’s idle management daemon.

Configuration

Configuration is done via the config file at ~/.config/hypr/hypridle.conf. A config file is required; hypridle won’t run without one.

To run hypridle at startup, add hypridle to your autostart commands in your Hyprland config.

General

Variables in the general category:

Listeners

Hypridle uses listeners to define actions on idleness.

Every listener has a timeout (in seconds). After idling for timeout seconds, on-timeout will fire. When action is resumed after idle, on-resume will fire.

You can define as many listeners as you want.

listener {
    timeout = 500                            # in seconds.
    on-timeout = notify-send "You are idle!" # command to run when timeout has passed.
    on-resume = notify-send "Welcome back!"  # command to run when activity is detected after timeout has fired.
}

Variables in the listener category:

Conditional timeouts

A listener can gate its on-timeout on external state with condition_cmd. When the timeout is reached, hypridle runs condition_cmd first; on-timeout fires only if it exits 0. A non-zero exit defers on-timeout.

Set condition_retry to keep re-checking while the user stays idle: hypridle re-runs condition_cmd every condition_retry seconds and fires on-timeout the moment it succeeds. With condition_retry = 0 (the default), a deferred on-timeout is simply skipped until the next idle cycle. Any user activity resets the listener and cancels a pending retry.

listener {
    timeout = 900                                          # 15min.
    on-timeout = systemctl suspend                         # suspend pc.
    condition_cmd = ~/.config/hypr/scripts/can-suspend.sh  # exit 0 = suspend, non-zero = stay awake.
    condition_retry = 30                                   # re-check every 30s while still idle.
}

#!/bin/sh
ss -tn state established '( sport = :ssh )' | grep -q . && exit 1
exit 0

general {
    lock_cmd = pidof hyprlock || hyprlock                                    # avoid starting multiple hyprlock instances.
    before_sleep_cmd = loginctl lock-session                                 # lock before suspend.
    after_sleep_cmd = hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })'  # to avoid having to press a key twice to turn on the display.
}

listener {
    timeout = 150                         # 2.5min.
    on-timeout = brightnessctl -s set 10  # set monitor backlight to minimum, avoid 0 on OLED monitor.
    on-resume = brightnessctl -r          # monitor backlight restore.
}

# turn off keyboard backlight, comment out this section if you dont have a keyboard backlight.
listener {
    timeout = 150                                           # 2.5min.
    on-timeout = brightnessctl -sd rgb:kbd_backlight set 0  # turn off keyboard backlight.
    on-resume = brightnessctl -rd rgb:kbd_backlight         # turn on keyboard backlight.
}

listener {
    timeout = 300                       # 5min
    on-timeout = loginctl lock-session  # lock screen when timeout has passed
}

listener {
    timeout = 330                                                                          # 5.5min
    on-timeout = hyprctl dispatch 'hl.dsp.dpms({ action = "disable" })'                    # screen off when timeout has passed
    on-resume = hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })' && brightnessctl -r  # screen on when activity is detected after timeout has fired.
}

listener {
    timeout = 1800                  # 30min
    on-timeout = systemctl suspend  # suspend pc
}

Locking on suspend and hibernate

The session is locked before going to sleep, not after resuming. Every route into sleep goes through logind’s PrepareForSleep signal — systemctl suspend, systemctl hibernate, systemctl suspend-then-hibernate, a listener with on-timeout = systemctl suspend, or closing the laptop lid with logind’s HandleLidSwitch. general:before_sleep_cmd therefore fires for all of them, including sleeps that hypridle did not initiate itself.

general {
    lock_cmd = pidof hyprlock || hyprlock     # run when the session is asked to lock.
    before_sleep_cmd = loginctl lock-session  # ask for the lock before sleeping.
}

before_sleep_cmd does not start the locker itself. loginctl lock-session only emits logind’s Lock signal for the session; hypridle picks it up and runs general:lock_cmd. Keeping the two apart means the locker is named in exactly one place, and a manual loginctl lock-session — from a keybind, for example — takes the same path as sleeping does.

Lid handling belongs to logind, not to Hyprland; see the warning about HandleLidSwitch. No extra bind is needed to lock on lid close: logind emits PrepareForSleep for that path too.

hypridle does not choose between suspend and hibernate, it only runs the command you give it. systemctl hibernate needs a working resume device, and systemctl suspend-then-hibernate suspends first and hibernates after HibernateDelaySec, set in /etc/systemd/sleep.conf.d/.

Waiting for the lock to be drawn

loginctl lock-session returns as soon as the signal has been sent, long before the locker has drawn anything. Without inhibition the system can freeze in that gap, and the frame that shows up on resume is the unlocked desktop, until the locker finally appears on top of it.

general:inhibit_sleep exists for this: hypridle takes a delay sleep inhibitor from logind and releases it once its before-sleep handling is done. What “done” means differs per mode:

• 1 releases the inhibitor as soon as before_sleep_cmd has been spawned, which is not enough for loginctl lock-session.
• 3 releases it only once the session is really locked, as reported over the hyprland-lock-notify-v1 protocol.
• 2 (the default) picks 3 only when it recognizes hyprlock, that is when before_sleep_cmd contains hyprlock, or when lock_cmd contains hyprlock and before_sleep_cmd contains lock-session. It falls back to 1 otherwise.

With any other lock screen app, set inhibit_sleep = 3 explicitly. Prefer that over padding before_sleep_cmd with a sleep: the inhibitor waits for the lock event itself instead of for a guess. Which mode was picked is printed at startup, as Sleep inhibition enabled - inhibiting until the wayland session gets locked.