swayidle(1)

📦
version 1.9.1 · 10 versions
, in arch rolling

💤 swayidle — the idle manager for Wayland, bestie 💤

Okay so real talk: swayidle(1) is from the General Commands Manual, and it's basically the friend who watches you do nothing and then makes stuff happen. Iconic behavior, honestly.

✨ NAME ✨

swayidle — Idle manager for Wayland. That's it. That's the whole job. She watches, she waits, she executes. 💅

🎀 SYNOPSIS 🎀

swayidle [options] [events...]

Short, sweet, and absolutely doing the most. 🫶

🌸 OPTIONS 🌸

  • -C <path> — The config file to use, bestie. By default she checks these paths in this exact order: $XDG_CONFIG_HOME/swayidle/config, then $HOME/.swayidle/config. Config file entries are events (like the ones in the EVENTS section below, keep reading 😌). And here's the tea: specifying events in the config and as arguments is not mutually exclusive — you can do both, she doesn't mind. 💖
  • -h — Show the help message and quit. A little "hi, here's what I do, bye" moment. ✨
  • -d — Enable debug output. For when you need to see everything she's thinking. 🔍
  • -w — Wait for the command to finish executing before continuing. Super helpful for making sure a before-sleep command has actually finished before the system goes to sleep.
⚠️ Heads up: using this option causes swayidle to block until the command finishes. Like, fully blocking. Don't say I didn't warn you. 💀
  • -S <seat-name> — Specify which seat to use. By default, if no name is specified, an arbitrary seat will be picked instead. She's chill like that. 🪑

🦋 DESCRIPTION 🦋

swayidle listens for idle activity on your Wayland compositor and executes tasks on various idle-related events. You can specify any number of events at the command line and in the config file. Any number. She's flexible. She's accommodating. She's literally the ideal roommate. 🌈

💜 EVENTS 💜

Okay this is the fun part, pay attention 👑

  • timeout <timeout> <timeout command> [resume <resume command> ] — Execute the timeout command if there is no activity for <timeout> seconds.

And if you also specify resume <resume command>, the resume command will be run when there is activity again. So it's like a little round trip: you get idle, she fires the timeout command, you come back, she fires the resume command. Glow up on both ends. ✨

  • before-sleep <command> — If built with systemd support, executes the command before systemd puts the computer to sleep. 😴
⚠️ Real note though: this only delays sleeping up to the limit set in logind.conf(5) by the option InhibitDelayMaxSec. A command that hasn't finished by then will keep running after resuming from sleep. So like, don't put anything eternity-long in there and expect it to be respected. 💀
  • after-resume <command> — If built with systemd support, executes the command after logind signals that the computer resumed from sleep. Welcome back, queen. 🌅
  • lock <command> — If built with systemd support, executes the command when logind signals that the session should be locked. 🔒
  • unlock <command> — If built with systemd support, executes the command when logind signals that the session should be unlocked. 🔓
  • idlehint <timeout> — If built with systemd support, set IdleHint to indicate an idle logind/elogind session after <timeout> seconds. Bonus detail: adding an idlehint event will also cause swayidle to call SetIdleHint(false) when run, on resume, unlock, etc. She's thorough like that. 🧚

Also, all commands are executed in a shell. Every single one. No exceptions. 🐚

🔥 SIGNALS 🔥

swayidle responds to the following signals:

  • SIGTERM, SIGINT — Run all pending resume commands. When finished, swayidle will terminate. A graceful exit, we love to see it. 🌸
  • SIGUSR1 — Immediately enter idle state. No waiting, no buildup, just straight into it. Main character energy. 💅

⭐ EXAMPLE ⭐

swayidle -w \
     timeout 300 'swaylock -f -c 000000' \
     timeout 600 'swaymsg "output * power off"' \
          resume 'swaymsg "output * power on"' \
     before-sleep 'swaylock -f -c 000000'

So what's happening here? This will lock your screen after 300 seconds of inactivity, then turn off your displays after another 300 seconds, and turn your screens back on when resumed. It will also lock your screen before your computer goes to sleep. Whole routine, fully handled. 👑

And here's the little detail that matters: to make sure swayidle waits for swaylock to lock the screen before it releases the inhibition lock, the -w option is used in swayidle, and -f in swaylock. Both of them. Don't skip one. 🙈

🌺 AUTHORS 🌺

Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open source contributors. For more information about swayidle development, see https://github.com/swaywm/swayidle. Shoutout to Drew and the whole crew, fr fr. 🫶

🌟 SEE ALSO 🌟

sway(5) swaymsg(1) sway-input(5) sway-output(5) sway-bar(5) loginctl(1)

Go read those too, they're all part of the same little ecosystem 💖

Okay that's the whole page!! Version/date stamp says 2026-10-25, and yeah — this was the swayidle(1) page from the General Commands Manual. Now go set a timeout and take a nap, you've earned it. 💤🎀

📦 where this page comes from