runwhenidle is a Linux utility that can be used to pause any Linux process when user activity is detected and resume it when user is idle. This can be useful for running computationally or IO-intensive program without degrading user's experience. It can run a command given to it or monitor an already running process.

The simplest way to start using runwhenidle is just by putting it in front of the command:

runwhenidle rsync -rva /home /backup

runwhenidle --start-monitor-after=10000 --timeout=30 --quiet ffmpeg -i file.mp4 file.mkv

In this example ffmpeg will run for 10 seconds uninterrupted. After 10 seconds pass, runwhenidle will start monitoring user activity and pause ffmpeg if user has been active within last 30 seconds. If user is inactive for 30 seconds, resume the operation of ffmpeg. --quiet option makes sure runwhenidle doesn't output anything other than the output of ffmpeg. Same command can be ran with the short versions of the arguments:

runwhenidle -a 10000 -t 30 -q ffmpeg -i file.mp4 file.mkv

runwhenidle --pid=12345 --pause-method=SIGTSTP --verbose

Start monitoring user activity and when user is active, pause process with PID 12345. Unpause it when user is inactive for 300 seconds. Use SIGTSTP which the process 12345 can handle or ignore instead of the default SIGSTOP that is always handled by the OS.

When runwhenidle determines that the user is active, it will send SIGSTOP (or optionally SIGTSTP) to the process and all its child processes. When the user activity stops, runwhenidle resumes the process by sending it and all the child processes SIGCONT signal. It then checks once per second if user activity has resumed, and once it is, pauses the process and its child processes again.

If runwhenidle was used to run a command (i.e. --pid parameter was not used) and it receives an interruption signal (SIGINT or SIGTERM), it will resume the process it is running if it is currently paused, and then sned the same signal to it to allow the process to handle the signal. runwhenidle then will stop checking for user activity and will wait for the process to exit.

On Wayland ext_idle_notification_v1 is used. This should work on any compsitor supporting it, but only tested it on KWin so far. As of 2026-06-09, the following composer support this Wayland extension:

On X11 runwhenidle uses XScreenSaverQueryInfo() to check when last user activity happened. When user is active, these checks happen as infrequently as possible to satisfy the desired inactivity timeout (default - every 5 minutes). When user is inactive, these checks happen once per second, to allow to restore the system responsiveness quickly.

runwhenidle will attempt to run using ext_idle_notificaition_v1, if it's not available, it will use X11, if that is also not available, it will display an error and will let the command continue without interruptions.

If WAYLAND_DISPLAY, XDG_RUNTIME_DIR, DISPLAY env variables do not exist, runwhenidle will try to guess their values. This makes it possible for it to work if ran from e.g. cron, both on Wayland and X11.

Ubuntu and Debian: Download the deb file attached to the latest release.

Arch: Available in AUR: https://aur.archlinux.org/packages/runwhenidle

Other Distros: You will need to compile runwhenidle yourself.

Make sure you have gcc, make, git, libxss-dev and libwayland-dev installed. Run make release. This should produce a binary file runwhenidle in the project directory.

If you want to install it system-wide, run sudo make install or simply sudo cp ./runwhenidle /usr/bin.

runwhenidle [OPTIONS] [shell_command_to_run] [shell_command_arguments]

1. When monitoring an existing pid, once it gets paused, it gets detached from the terminal it was in. Running "fg" command could be a workaround to get it reattached, but it is required after every pause.

Make sure you have docker installed and run:

make debian-package

The .deb file will be generated in package-build/ directory.