UNCLUTTER(1)

💖 unclutter(1) 💖

okay bestie, welcome to the General Commands Manual, section 1, the one and only unclutter — and yes, I'm about to make a cursor-hiding utility sound like the most iconic thing that ever happened to your X session. because honestly? it kind of is. 🦋

---

✨ NAME ✨

unclutter — remove idle cursor image from screen

like. that's it. that's the whole job. it takes your mouse pointer and goes poof when you're not using it. main character energy: present, then dramatically absent. 💅

---

🎀 SYNOPSIS 🎀

unclutter [-display|-d display] [-idle seconds] [-keystroke] [-jitter
pixels] [-grab] [-noevents] [-reset] [-root] [-onescreen] [-visible]
[-regex] [-not|-notname name ...]  [-notclass class ...]

she's got a lot of little accessories. we love a girl with options. 🫶

---

🌸 DESCRIPTION 🌸

so unclutter removes the cursor image from the screen so it stops being that one friend who stands directly in front of the thing you're looking at. after the cursor hasn't moved for a given amount of time — gone. not visible. not blocking. slay. ✨

but she has boundaries, okay? she does not do this if the cursor is in the root window, and she does not do this if a button is down. holding a button = you're doing something, she's not gonna yank your pointer out from under you. rude.

and if you have one of those mice that twitches like it's had three espresso shots — small movements caused by noise — she tries to ignore that jitter. lowkey a considerate queen. 💜

---

💅 OPTIONS 💅

• -display — followed by the display to open. that's the whole vibe. point her at a display, she'll go there.
• -idle — followed by the number of seconds between polls for idleness. the default is 5. and yes, she supports subsecond idle times, because we live in a fast-paced world and nobody has time to wait a whole second. ⏱️
• -keystroke — tells unclutter not to use a timeout to decide when to remove the cursor, but to instead wait until a key has been pressed. (released, really. it's a release thing. details matter.) ⌨️
• -jitter — followed by the amount of movement of the pointer that is to be ignored and considered as random noise. the default is 0, so by default she trusts your hand completely. bold of her. 😌
• -grab — means use the original method of grabbing the pointer in order to remove the cursor. ngl, this one often doesn't interoperate too well with some window managers. it's giving legacy. it's giving "we don't talk about her." 💀
• -noevents — stops unclutter from sending a pseudo EnterNotify event to the X client whose cursor has been stolen. sending that event helps programs like emacs think they have not lost the pointer focus. this option exists for backwards compatibility, in case some clients get upset about it. we love a chill option for the sensitive ones. 🙈
• -reset — resets the timeout for idleness after the cursor is restored for some reason (like a window being pushed or popped) even though the x y coordinates of the cursor have not changed. normally, the cursor would immediately be removed again. so this is the "actually, give me a sec" option. 🎀
• -root — means remove the cursor even if it is on the root background, where in principle it should not be obscuring anything useful. she said in principle. she still lets you do it. 🤷♀️
• -onescreen — restricts unclutter to the single screen specified as display, or the default screen for the display. normally, unclutter will unclutter all the screens on a display. so this is the "one screen only, I'm monogamous about my monitors" flag. 🖥️
• -visible — ignore visibility events (does not apply to -grab). if the cursor never gets hidden, despite a generous -jitter value, try this option. this is your plan B. your backup bestie. your "have you tried turning it off and on again" but for events. ⭐
• -not — followed by a list of window names where the cursor should not be removed. the first few characters of the WM_NAME property on the window need to match one of the listed names. this argument must be the last on the command line. it's the grand finale. nothing comes after her. 🚫
• -notname — is exactly the same as -not. literally identical. twins. matching outfits and everything. 👯
• -notclass — is similar to -notname, except that the WM_CLASS property of the window is used instead. this argument must be the last on the command line, and so cannot be used with -not or -notname. you can only pick one queen per command line, sorry. 👑
• -regex — treats the first name or class (see above) as a regular expression. this means that -regex -not foo bar will not work as expected; instead use -regex -not 'foo|bar'. so like. put the alternation inside the quotes, bestie, don't hand her two separate words and expect magic. 🪄

---

😭 LIMITATIONS 😭

not everything is perfect and we have to talk about it.

the -keystroke option may not work — that is, the cursor will not disappear — with clients that request KeyRelease events. games and Xt applications using KeyUp in their translation tables are the most likely to suffer from this problem. the most feasible solution is to extend unclutter to use the XTest extension to get all keyboard and mouse events, though this of course requires XTest to be in the server too. so like, a fix exists, but it's a whole thing. 💀

also: the -keystroke option does not distinguish modifier keys from keys which actually generate characters. if desired, this could be implemented in a simple way by using XLookupString to see if any characters are returned. she's telling you how she could be better. icon behaviour, honestly. 🌈

---

🔥 DIAGNOSTICS 🔥

if you ever see this message:

someone created a sub-window to my sub-window!

...that means unclutter thinks a second unclutter is running, and tried to steal the cursor by creating a sub-window to the sub-window already used to steal the cursor. this situation quickly deteriorates into a fight no one can win, so it is detected when possible and the program gives up. 💀 not a rivalry, not a beef, just two girls with the same job and one cursor between them. she's not doing that. she's walking away. periodt. 🚶♀️

---

💜 AUTHOR 💜

Mark M Martin. cetia 7feb1994. mmm@cetia.fr

---

and that's the whole page, bestie — from the General Commands Manual, UNCLUTTER(1), written by Mark M Martin (cetia, 7feb1994, mmm@cetia.fr) and dated all the way back to that 1994 moment in time. she's been hiding cursors since before some of us were born and she's still serving. 🎀✨💖