xautolock(1)

📦 version 2.2, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

xautolock — fire up programs in case of user inactivity under X 💖

okay so real quick, bestie: this is xautolock(1) from the General Commands Manual (section 1, commands, the good stuff). It's the page all about xautolock. Let's get into it 🫶

🎀 VERSION 🎀

This man page applies to xautolock version 2.2. Periodt. That's the version this page is describing. 📌

🦋 SYNOPSIS 🦋

xautolock [-help] [-version] [-time mins] [-locker locker] [-killtime
          killmins] [-killer killer] [-notify margin] [-notifier
          notifier] [-bell percent] [-corners xxxx] [-cornerdelay secs]
          [-cornerredelay altsecs] [-cornersize pixels] [-secure]
          [-resetsaver] [-nocloseout] [-nocloseerr] [-noclose]
          [-disable] [-enable] [-toggle] [-exit] [-locknow] [-unlocknow]
          [-nowlocker locker] [-restart] [-detectsleep]

that's the whole menu of flags right there, no notes 💅

🌸 DESCRIPTION 🌸

okay so here's the vibe. xautolock sits there and monitors the user activity on an X Window display. If none is detected within mins minutes, a program is started as specified by the -locker option. 🕵️♀️

Xautolock will typically be used to lock the screen — hence its primary name, iykyk — but honestly? it really doesn't care what program you make it start. no cap. For this reason, xautolock does not interfere with the default X screen saver, unless the -resetsaver option is used. This implies that it is the job of the locker or the user to take the appropriate actions if the default screen saver is to be disabled. The only real assumption made by xautolock is that a new countdown starts as soon as the locker exits. that's it, that's the whole lore 🫶

🔔 the warning signal situation

In the presence of the -notify option, a warning signal will be issued margin seconds before starting the locker. Warning signals come in two kinds:

You can use the -notifier option to specify the command to be issued to perform notification. 📣
Alternatively, you can let xautolock ring the bell. In this case, the -bell option specifies the loudness of the signal in percent, as described in the XBell man page. 🔔

🧭 corners, corners, corners

You can tell xautolock to take special actions when you move the mouse into one of the corners of the display and leave it there, by using the -corners, -cornerdelay, -cornerredelay and -cornersize options. This works as follows:

The xxxx argument to the -corners option must consist of exactly 4 characters from the following set: '0', '+', '-'. Each one of these specifies what xautolock should do when the mouse enters a small square area located in each of the corners of the screen. The corners are considered in the following order: top left, top right, bottom left, bottom right. 🦋

'0' indicates that xautolock should ignore the corner. 🙈
'+' indicates that xautolock should start the locker after secs or altsecs seconds (see below for the difference between both), unless the mouse is moved or keyboard input is received. 🔥
'-' indicates that xautolock should not start the locker at all. 💀

The pixels argument specifies the size in pixels of the corner areas. 📐

Most users of the -corners option want the locker to activate within a very short time interval after they move the mouse into a '+' corner. This can be achieved by specifying a small value for the -cornerdelay option. However — and this is the important part, bestie — if the mouse is subsequently left where it is, xautolock will almost immediately start a new locker right after the user quits the current one. 😭 To prevent this from happening, the -cornerredelay option can be used to specify the time-out interval to be used if and only if the mouse is sitting in a '+' corner and has not been moved since the previous locker exited. chef's kiss, honestly 👑

🛑 disable, enable, toggle

A running xautolock process can be disabled (unless if the -secure option has been specified), in which case it will not attempt to start the locker.

To disable an already running xautolock process, use the -disable option.
To re-enable it, use -enable.
To toggle it between both states, use -toggle.

Using this method is preferable to sending it SIGSTOP and SIGCONT signals, because while disabled xautolock will still be emptying its event queue. no cap, that's the whole reason ✨

👋 exit

A running xautolock process can also be told to exit (unless if the -secure option has been specified). To do this, use the -exit option. bye bestie 🫶

⚰️ killtime + killer

The -killtime and -killer options allow, amongst other things, to implement an additional automatic logout, on top of the automatic screen locking. In the presence of one or both of these options, a secondary timeout will be triggered killmins after starting the locker (unless user activity is detected in the mean time). Upon expiration of this secondary timer, the killer program is run.

Note that, despite the name of the options, xautolock really doesn't care what the killer does in reality. If it doesn't (indirectly) cause xautolock to get killed, and assuming that no user activity is detected, the secondary trigger will periodically expire every killmins minutes for as long as the locker runs. 🔁

🔒 secure mode, for the sysadmins

In combination with -killtime and -killer, the -secure option allows system administrators to enforce xautolock as a part of their security procedures, and to prevent people from locking shared displays for an excessive amount of time.

One way to achieve this is to start xautolock (using -secure and optionally -killtime and -killer) from within XDM's Xsession file in such a way that the session automatically ends if xautolock itself is killed. main character security energy, fr fr 🛡️

🚰 stdout / stderr behaviour

By default xautolock closes stdout and stderr. This prevents the locker from writing error messages to these files in case you manually lock your display. 💅

The -nocloseout, -nocloseerr and -noclose options cause xautolock to not close stdout and/or stderr.

On some platforms users of xnlock will need to use -nocloseout, in order to make xnlock's witty sayings show up. 😭✨ These options can also be used for debugging cases in which locker invocation is not successful. 🔍

🐙 multi-headed displays

Xautolock is capable of managing multi-headed displays. like, it just does that. iconic. 💜

✨ OPTIONS ✨

okay bestie this is the main event, the whole reason you're here. every single flag, no skips, let's go 🫶

-help — prints a lil help message and then dips. that's it, that's the whole thing.
-version — prints the version number and exits. quick lil flex.
-time — sets the primary timeout interval. the default is 10 minutes and the minimum is 1 minute. don't get cute and go lower than that 💅
-locker — tells xautolock which locker to use. the default is xlock. heads up: if your locker has multiple words in it, you must wrap it in quotes, no cap. and listen — so it can find the program using your PATH, xautolock feeds the locker command to /bin/sh, so it needs to be something your /bin/sh can actually understand. since that's typically a Bourne shell, ~ expansion most likely will not work. sad but true 😭
-killtime — sets the secondary timeout in minutes, counted after the locker starts. this timer is only active for as long as the locker is running, and it gets reset every single time user activity is detected. if it expires before the locker exits, the killer command gets run. default is 20 minutes, minimum is 10 minutes. also this option is only useful alongside -killer — otherwise it's just vibes ✨
-killer — specifies the killer to be used. the default is none (as in, nothing happens, we're peaceful here). if killer contains multiple words, quote it, periodt. and same deal as locker: to locate the program via your PATH, xautolock feeds the killr command to /bin/sh, so it should be understandable for whatever shell your /bin/sh is. because this typically is a Bourne shell, ~ expansion most likely will not work. 🥲
-notify — warns the user margin seconds before locking. the default is to not warn the user at all (surprise lock, jumpscare 🫣). if you use it together with -cornerdelay or -cornerredelay, the notification margin used is the minimum of margin, secs and/or altsecs.
-notifier — specifies the notifier to be used. default is none. this option is only useful with -notify. multiple words? quotes, babe. and to use your PATH, xautolock feeds the notifier command to /bin/sh, so it should be understandable for whatever shell your /bin/sh is. typically a Bourne shell, so ~ expansion most likely will not work. 💀
-bell — sets the loudness of the notification signal when there's no -notifier in play. default is 40 percent. only useful with -notify. ding ding 🔔
-corners — defines the special actions taken when the mouse enters one of the corners of the display. default is 0000, which means no special action at all. corners stay unbothered ✨
-cornerdelay — how many seconds to wait before reacting to the mouse entering a '+' corner. default is 5 seconds.
-cornerredelay — how many seconds to wait before reacting again if the current locker exits while the mouse is still sitting in a '+' corner. the default is for altsecs to equal secs.
-cornersize — the size, in pixels, of the corner areas. default is 10 pixels.
-resetsaver — makes xautolock reset the X screen saver after successfully starting the locker. this is typically used when the locker isn't really meant to lock the screen, but to replace the default X screen saver. important note bestie: the default screen saver is not disabled, only reset. also, using -resetsaver will interfere with DPMS monitors, because the power down time out will also be reset. default is not to reset the screen saver.

see the xset man page for more info on managing the X screen saver.

-detectsleep — tells xautolock to detect that the computer has been put to sleep. it does this by noticing that time has jumped by more than 3 seconds. when that happens, the lock timer is reset and the locker program is not launched, even if the primary timeout has been reached. this is typically used to stop the locker from launching when you wake up a laptop. good morning sunshine ☀️
-secure — runs xautolock in secure mode. in this mode, xautolock becomes immune to the effects of -enable, -disable, -toggle, and -exit. default is to honour those actions. so basically: secure mode = nobody can tell it what to do 🔒
-nocloseout — don't close stdout.
-nocloseerr — don't close stderr.
-noclose — closes neither stdout nor stderr. keeping both channels open, we love a communicative icon 💬
-disable — disables an already running xautolock process (if there is one, and it doesn't have -secure switched on). either way, the current invocation of xautolock exits.
-enable — enables an already running xautolock process (if there is one, and it doesn't have -secure switched on). either way, the current invocation of xautolock exits.
-toggle — toggles an already running xautolock process (if there is one, and it doesn't have -secure switched on) between its disabled and enabled modes of operation. either way, the current invocation of xautolock exits.
-exit — causes an already running xautolock process (if there is one, and it doesn't have -secure switched on) to exit. either way, the current invocation of xautolock also exits. everyone's leaving, it's giving end of party 🎀
-locknow — causes an already running xautolock process (if there is one, if it doesn't have -secure switched on, and isn't currently disabled) to lock the display immediately. either way, the current invocation of xautolock exits.
-unlocknow — causes an already running xautolock process (if there is one, if it doesn't have -secure switched on, and isn't currently disabled) to unlock the display immediately (if it's locked) by sending the locker a SIGTERM signal. either way, the current invocation of xautolock exits.
-nowlocker — specifies the locker to use if the lock is initiated with the -locknow option. the default is to use the locker program given with -locker, which defaults to xlock.
-restart — causes an already running xautolock process (if there is one and it doesn't have -secure switched on) to restart. either way, the current invocation of xautolock exits. glow up era 🔄

🌈 RESOURCES 🌈

okay so you can also set all this stuff via X resources instead of typing flags like a menace. here's the whole list, no crumbs:

time — the primary timeout. Numerical.
locker — the locker. no quotes needed, even if the locker command contains multiple words.
killtime — the secondary timeout. Numerical.
killer — the killer. no quotes needed, even if the killer command contains multiple words.
notify — the notification margin. Numerical.
notifier — the notifier. no quotes needed, even if the notifier command contains multiple words.
bell — the notification loudness. Numerical.
corners — the corner behaviour, as explained above.
cornersize — the size of the corner areas. Numerical.
cornerdelay — the delay of a '+' corner. Numerical.
cornerredelay — the alternative delay of a '+' corner. Numerical.
resetsaver — reset the default X screen saver. Boolean.
nocloseout — don't close stdout. Boolean.
nocloseerr — don't close stderr. Boolean.
noclose — close neither stdout nor stderr. Boolean.

resources can go in your ~/.Xresources or ~/.Xdefaults file (whichever your system uses) and then get merged in via the xrdb(1) command. you can specify them either for the class Xautolock, or for whatever name your xautolock program has been given. this is lowkey so useful if xautolock is being used for stuff other than just locking the screen.

for example 💖: if you have two copies of xautolock, one called "xmonitor" and one called "xlogout", then both will honour this:

Xautolock.corners: ++++

in addition, "xmonitor" will honour:

xmonitor.cornersize: 10

while "xlogout" will honour:

xlogout.cornersize: 5

and the rules of the house: each command line option takes precedence over the corresponding (default) resource specification. flags on top, always 👑

💀 KNOWN BUGS 💀

real talk, no sugarcoating, here's where it gets a lil messy:

the -disable, -enable, -toggle, -exit, -locknow, -unlocknow, and -restart options all depend on access to the X server to do their work. which means they'll get suspended if some other application has grabbed the server all for itself. rude tbh.

if, when creating a window, an application waits more than 30 seconds before selecting KeyPress events on non-leaf windows, xautolock may interfere with the event propagation mechanism. this effect is theoretical and has never been observed in real life. it can only occur if xautolock has been compiled without support for both the Xidle and the MIT ScreenSaver extensions, or if the X server itself doesn't support those extensions.

xautolock does not always properly handle the secure keyboard mode of terminal emulators like xterm, since that mode will stop xautolock from noticing the keyboard events happening on the terminal. so sometimes xautolock thinks there's no keyboard activity when there totally is 😭. again, this can only occur if xautolock was compiled without support for both the Xidle and the MIT ScreenSaver extensions, or if the X server doesn't support those extensions.

xautolock does not check whether notifier and/or locker are actually available. it just trusts. bold of it.

the xautolock resources have dummy resource classes. yeah. that's the whole note.

🦋 SEE ALSO 🦋

X(1), xset(1), xlock(1), xnlock(1), xscreensaver(1).

👑 COPYRIGHT 👑

versions 2.0 and above of xautolock are available under version 2 of the GNU GPL. earlier versions are available under other conditions. for more info, see the License file. 📜

💖 AUTHORS 💖

xautolock was conceived, written, and performed by... a whole duo, bestie. Like, an actual two-person collab and they ATE:

Michel Eyckmans (aka MCE) 🎀
Stefan De Troch ✨

Periodt. Icons only.

Got questions? Need help? Wanna suggest a feature? Found a bug and you're big mad about it? Slide into the inbox, fr fr:

Please send queries for help, feature suggestions, bug reports, etc. to mce@scarlet.be.

That's the whole vibe. They literally want to hear from you. 🫶

🌸 SPECIAL THANKS TO 🌸

Kris Croes 💅

That's it, that's the list. One name. One legend. Not everyone can say they got a whole special-thanks section named after them and yet here we are. 👑

okay so that's genuinely the end of the page, bestie 😭 and it's giving December 28, 2007, which is the date stamped on this xautolock(1) page, from the source/version footer — yes, your girl is ancient and still slaying, no cap. Go lock your screen, go live your life. mwah 💖🦋🌸

📦 where this page comes from

debian bookworm: xautolock 1:2.2-8 · GPL-2.0-only
ubuntu jammy: xautolock 1:2.2-7 · GPL-2.0-only
ubuntu noble: xautolock 1:2.2-8 · GPL-2.0-only
ubuntu questing: xautolock 1:2.2-8
ubuntu resolute: xautolock 1:2.2-8build1 · GPL-2.0-only
ubuntu stonking: xautolock 1:2.2-8build1 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms