These FAQs are about the X11 (Linux, BSD, etc.) version of XScreenSaver.
These FAQs don't apply to the MacOS version. There aren't any FAQs about the MacOS version because, well, unlike Linux, MacOS just works. Sad but true.
Please also read the manual. I think it's a pretty good manual. It's long, but it's subdivided fairly sensibly. This document answers the questions that are answered in the manual that people ask about a lot anyway, plus some random other questions that didn't really seem to fit in the manual itself.
Alas, this shitshow is ongoing. You can read about it over on my blog.
If you are using Debian, install the newer version from their so-called "unstable" packages. Scroll down, find the .deb package for your architecture, and install that.
The Debian maintainers think that it's reasonable to package and redistribute software to their users that is years old without giving them any easy way to upgrade to a recent version. This is bad and they should feel bad. You should use distros that give you the option of keeping your software up to date, and that understand that "stable" and "ancient" are not the same thing.
If you are using an out-of-date Red Hat / Centos based system, you can probably find recent XScreenSaver executables at rpmfind.net.
If that doesn't work, you'll have to build from source.
You do this by using a program that can display a list of images on the root window. One such program, glslideshow is included with xscreensaver. It displays a sequence of images, slowly panning and zooming through them, and fading smoothly from one image to the next. Just select "GLSlideshow" in the xscreensaver control panel, and enter the directory (or RSS URL) where your images live on the "Advanced" tab.
If you want to only run a slideshow, then select GLSlideshow in "Only One Screen Saver" mode. Otherwise, the slideshow it will be just one of the display modes that xscreensaver will select from randomly, and run for the length of time specified in the `cycle' preference.
If your graphics card is extremely old, you may find that glslideshow doesn't run fast enough. This is unlikely: any graphics card manufactured in this century should be fast enough. But, if you try it and it is slow, then you'll want to run a different program. Two good choices for displaying slideshows on very old machines with no graphics acceleration are chbg and xv. To use those, you need to add a line to the `programs' preference in your .xscreensaver file:
|GLSlideshow:||Just select it from the list; and specify your image
directory on the "Advanced" tab.
default-n: chbg -xscreensaver -randomize \ -interval 0.30 \ -R $HOME/images/ \n\
default-n: xv -root -rmode 5 -random \ -viewonly -wloop -wait 30 \ $HOME/images/*.jpg \n\
To play MP4, MPEG, QuickTime, FLV and AVI videos:
Install mpv and add something like the following to the `programs' preference in your .xscreensaver file:
"My Movie" mpv --really-quiet --no-audio --fs --loop=inf \ --no-stop-screensaver \ --wid=$XSCREENSAVER_WINDOW \ $HOME/movies/poop.mp4 \n\Duplicate those lines for each other movie you would like to play.
It's also possible to encapsulate the above into a single shell script which would pick a movie file at random from a directory and play that. Several people have written such things; Google it.
To play SWF Flash animations:
Macromedia's stand-alone Flash player has xscreensaver support, as of version 6.0.79 and later. To use it, put a line like this in the `programs' preference in your .xscreensaver file:
"My Flash" gflashplayer -root $HOME/movies/my_flash.swf \n\
To play anything else:
See the 'Advanced' tab on the xscreensaver control panel.
You can do that using xscreensaver-command -watch. See the xscreensaver-command manual for an example.
Don't log in as root.
Please note that xscreensaver works fine as a screen saver when you are logged in as root: it will not, however, lock your screen when you are logged in as root. This is for good and insurmountable security reasons.
In order for it to be safe for xscreensaver to be launched by xdm, certain precautions had to be taken, among them that xscreensaver never runs as root. In particular, if it is launched as root (as xdm is likely to do), xscreensaver will disavow its privileges, and switch itself to a safe user id (such as "nobody".)
An implication of this is that if you log in as root on the console, xscreensaver will refuse to lock the screen (because it can't tell the difference between root being logged in on the console, and a normal user being logged in on the console but xscreensaver having been launched by the xdm "Xsetup" file.)
The solution to this is simple: you shouldn't be logging in on the console as root in the first place! (What, are you crazy or something?)
Proper Unix hygiene dictates that you should log in as yourself, and su to root as necessary. People who spend their day logged in as root are just begging for disaster.
Don't log in as root.
As described above, xscreensaver disavows its privileges if it finds that it is running as root, for security reasons. An unfortunate side-effect of this is that it may conflict with cookie-based authentication.
If the X server is running as one user (e.g., "root") and xscreensaver is running as another user (e.g., "nobody") then the xscreensaver process might not be allowed to connect to the X display at all, since it isn't running as the same user.
One way around this is to run the command
But beware! This will give access to the X server to anyone capable of logging in to the local machine, and in some environments, that could be considered an unacceptable security risk.
This is discussed in more detail in the "Using GDM" section of the xscreensaver manual.
If you're logged in as a normal user, and you `su' to root to run some sysadmin-oriented X program, you might find yourself staring at an error message like
% su % Password: # rooty-program Xlib: connection to ":0.0" refused by server Xlib: Invalid MIT-MAGIC-COOKIE-1 key
There are two ways around this. The first is to allow any program running on the local machine to access your X server:
% xhost +localhost localhost being added to access control list % su % Password: # rooty-program ...Ok! # exit % xhost -localhost localhost being removed from access control list
If you don't trust the other people who have accounts on the local machine, that would not be a good idea, because they will then be able to snoop your display. However, you can make it so that only root has access to your X display. This is slightly more complicated, but safer:
% su % Password: # xauth -f /home/user/.Xauthority nextract - $DISPLAY | xauth nmerge - # rooty-program ...Ok! # exit
The above will extract the X access cookie from the .Xauthority file in your home directory, and write it into the .Xauthority in root's home directory, making it possible for root to access your display.
(Note that this is not a solution for making xscreensaver be able to lock the screen as root. Stop logging in as root and you will stop caring about that.)
Maybe it doesn't need to be on your system. Try it and see.
On many systems, only "root" can access the password database. In order to function as a screen-locker, xscreensaver needs to be able to tell when you've typed the correct password. That means that on those systems, xscreensaver needs to run as root, briefly, at startup. Immediately after startup, and before connecting to the X server, xscreensaver disavows its root privileges, and from then on, runs as an unprivileged user. The amount of code that actually runs as root is very small, and has been examined with great care.
If your system doesn't use shadow passwords, or if your system uses PAM (and PAM is installed correctly!), then xscreensaver will work even if it is not setuid. If you're concerned, try turning off the setuid bit, restart it, and see if you can still unlock the screen. If so, great.
I'm sorry. But the fact is that an X server crash is, by definition, a bug in the X server.
The rule is that absolutely nothing a client program
throws at the X server should make it crash. When an X client does
something wrong, the server is supposed to return an error, causing
the client to exit. If the server itself goes down, that's a bug in
the server. There may also be a bug in the
This also goes for DRI, GL, and any vendor- or hardware-specific libraries you might be using. If something in xscreensaver caused your display to freeze, or logged you out, or made your monitor explode, I can pretty much guarantee you that the bug is in your X server or your video driver, and not in xscreensaver.
Try upgrading your X server and video drivers. If that doesn't help, you can try running each display mode in turn until you figure out which one is triggering the X server bug. It is most likely to be one of the GL (3D) screensavers, since those are the ones that actually take advantage of your video hardware. When you figure out which one is causing the crash, you now have a reproducible test case! Congratulations. Please report that to the vendor of your X server and/or your video drivers so that they can fix the problem.
Turning off acceleration in your X server may also make the problem go away, but that will also slow your machine down a lot.
If that still brings you no joy, then I recommend switching to MacOS. I did.
The MacOS version of XScreenSaver works great, incidentally, and has never, ever crashed my machine.
On most X11 systems, this is unfortunately the case, and there's no way around it. XScreenSaver notices all keyboard activity; and every few seconds, it checks the position of the mouse. If there have been no keystrokes or mouse motion, it assumes you are idle. It cannot detect mouse clicks, nor the scroll wheel.
This is because, for no good reason, the X Window System does not allow programs to "snoop" on mouse clicks (though snooping of keystrokes and mouse positions is permitted!)
Some window managers allow programs to pop windows above xscreensaver, and some do not.
Every few minutes, xscreensaver will raise itself above any other windows that have popped up, but it can't prevent other programs from popping up their windows in the first place. So they will appear for a little while, and then be hidden.
If this is happening and it bothers you, switching to a different window manager may fix it.
You might consider this a bug in your window manager (though some consider it a feature.) If you think it's a bug, then the magic incantation to repeat to the author of your window manager is as follows: "you should be mapping windows with XRestackWindows instead of XRaiseWindow, to ensure that managed windows always appear below override-redirect windows."
It is also possible that the application that is popping up the window is doing so using an override-redirect window of its own. (This is currently the case with GTK_WINDOW_POPUP style dialogs.) In that case, it is impossible for either xscreensaver or the window manager to prevent those windows from popping up, since override-redirect windows, by definition, bypass the window manager. So, there's no way around that without either: A) changing those applications to use normal windows instead, or B) creating a new extension to X11 itself.
In particular, Metacity can't prevent these dialogs any more than xscreensaver can. (GNOME bug 154529.)
Run the xscreensaver-demo program. On the left is a list of all of the demos. Each has a checkbox next to it. Un-check the ones you don't like. Only the ones that are checked will be automatically run by the xscreensaver daemon (though you can still run the others explicitly by double-clicking on them in the xscreensaver-demo window.)
After you've run xscreensaver-demo once, you will have a .xscreensaver file in your home directory. You can also just edit that file directly: disable the ones you don't like by putting a minus (-) at the beginning of the line. The xscreensaver daemon will notice when the file has changed and reload it automatically.
Instead of deleting them from the file, comment them out by putting a minus (-) at the beginning of the line. Or, just use the xscreensaver-demo program to de-select the ones you don't like, which does the same thing.
Your .xscreensaver file needs to contain a complete list of all the available screen savers so that xscreensaver can tell when new ones have been added, as a result of a newer version of xscreensaver having been installed.
If you want that, there is a program called Brightside that lets you assign configurable actions to your screen corners, including screen saver actions.
The reason this behavior is not built in to xscreensaver is that I find it non-obvious, non-discoverable, and counter-intuitive. I believe that an interface like the existing Gnome "Lock Screen" panel icon is far more sensible.
While it's not a bad idea, this is difficult to implement in such a way that it would work on all systems. On some systems, xscreensaver decides when to activate/deactivate by monitoring keyboard and mouse activity directly. But on some systems, a more efficient method is used: instead, the X server sends messages to xscreensaver telling it when to activate and deactivate.
So in the latter case, xscreensaver only knows that it has been told to deactivate: it has no way of knowing which key was pressed.
If gdmflexiserver is installed on your system, there should be a "New Login" button on xscreensaver's unlock dialog. If that doesn't appear or doesn't work right, check the setting of the "newLoginCommand" preference in the XScreenSaver.ad app-defaults file.
Yes, it should. Unfortunately, that's not possible with current versions of XFree86 or XOrg. It's as if the developers of X11 and the Linux kernel want to make it as hard as possible for you to lock your screen.
This keystroke kills the X server, and on some systems, leaves you at a text console. If the user launched X11 manually, that text console will still be logged in. To disable this keystroke globally and permanently, you need to set the DontZap flag in your xorg.conf or XF86Config or XF86Config-4 file (whichever name is in use on your system). See the manual for XF86Config (or variant) for more details.
These keystrokes will switch to a different virtual console, while leaving the console that X11 is running on locked. If you left a shell logged in on another virtual console, it is unprotected. So don't leave yourself logged in on other consoles. You can disable VT switching globally and permanently by setting DontVTSwitch in your xorg.conf, but that might make your system harder to use.
This is the Linux kernel "OOM-killer" keystroke. It shoots
down random long-running programs of its choosing, and so might
might target and kill xscreensaver, and there's no way for
xscreensaver to protect itself from that. You can
disable it globally with:
This keystroke kills any X11 app that holds a lock, so typing this will kill xscreensaver and unlock the screen. This "feature" showed up in the X server in 2008, and as of 2011, some vendors are shipping it turned on by default. How nice. You can disable it by turning off AllowClosedownGrabs in xorg.conf.
There's little that I can do to make the screen locker secure so long as the kernel and X11 developers are actively working against security. The strength of the lock on your front door doesn't matter much so long as someone else in the house insists on leaving a key under the welcome mat.
In an ideal world, there would be a single X11 request named something like XGrabMagicKeys() that would, analagously to XGrabKeyboard(), disable all of these magic keystrokes until the grab was released or the program exited. It should be an X11 call, not an ioctl(), and especially not a root-only ioctl(). Needless to say, no such interface exists.
You can accomplish these things and more by installing the proper PAM module. XScreenSaver doesn't need to be modified at all, since it simply asks the PAM stack to authenticate. Doing it this way also means that the console login prompt can also be made to authenticate in the same way, not just xscreensaver. Check out PAM NFC or similar projects.
Run the xscreensaver-demo program: when its window comes up, one of the elements in the list of display modes will be highlighted by default. That is the one that was most recently running.
People often suggest that I put the name of the current hack on
the password dialog box. I'm not going to do that, because that
would be a (non-
You can still blank and/or lock your screen, while denying yourself the pleasure of graphical screen savers, by running xscreensaver-demo and selecting "Blank Screen Only" from the "Mode" option menu.
But is that really necessary? Let's address the real problem:
when xscreensaver is blanking the screen, it runs its graphics demos
at a low priority, so they should not be stealing cycles from other
The exception to this -- and the probable cause of what you are
experiencing -- is the OpenGL (3D) demos, when running on machines
without 3D hardware. If you don't have hardware- So, a less drastic fix, in that situation, is to not run the GL
demos: un-check any of the 3D hacks, and you can still run the
non-resource-itensive graphics demos.
However, the recommended fix is that you turn over the cushions
in your couch, collect the spare change you find, and once you've
come up with $10, spend it on a video card that was manufactured
after 1998. You will then have a video card with 3D acceleration,
and everything will work much, much better.
It doesn't even need to be fast 3D hardware: things will
be notably improved if there is any 3D hardware at all.
Seriously, this shouldn't be a problem for any graphics card that
was manufactured in the Twenty-First Century. So, if you have a
modern card and OpenGL programs aren't fast, then you have a driver
problem: the card's 3D hardware is not being used at all, and all
the 3D rendering is happening in software.
Fix that instead.
So, a less drastic fix, in that situation, is to not run the GL demos: un-check any of the 3D hacks, and you can still run the non-resource-itensive graphics demos.
However, the recommended fix is that you turn over the cushions in your couch, collect the spare change you find, and once you've come up with $10, spend it on a video card that was manufactured after 1998. You will then have a video card with 3D acceleration, and everything will work much, much better.
It doesn't even need to be fast 3D hardware: things will be notably improved if there is any 3D hardware at all. Seriously, this shouldn't be a problem for any graphics card that was manufactured in the Twenty-First Century. So, if you have a modern card and OpenGL programs aren't fast, then you have a driver problem: the card's 3D hardware is not being used at all, and all the 3D rendering is happening in software.
Fix that instead.
If you are using mpv or mplayer, put this in your ~/.mplayer/config file:
If you're using something else:
That's kind of lame, I know. You should ask the author of the movie-playing software you are using to support xscreensaver.
The only way that xscreensaver can tell that the monitor is in power-saving mode is by asking the X server. There is a server extension specifically for asking these sorts of questions, called "XDPMS", and xscreensaver uses that.
So it may be that your X server doesn't support the XDPMS extension (you can tell by running "xdpyinfo"). Or, it may be that the extension is supported, but the X server doesn't actually know how to talk to your hardware to ask it whether it is powered on or off. The latter is especially likely on laptops: many laptops have monitor power-saving behavior built in at a very low level that is invisible to Unix and X. On such systems, you can typically only adjust the power-saving delays by changing settings in the BIOS in some hardware-specific way.
If the Power Management settings in the Preferences panel are grayed out, then that means that either: xscreensaver was compiled without DPMS support; or xscreensaver believes that your system does not support power management.
Short answer: your mouse is getting bumped. Cats, trucks, doors, and earthquakes are likely culprits.
Slightly longer answer: XScreenSaver is responsible for blanking and locking the screen and drawing pretty pictures. However, the X server itself is responsible for powering down the monitor. XScreenSaver is smart enough to ignore tiny mouse motions: if your mouse only moves by a couple of pixels, XScreenSaver ignores that: it only un-blanks the screen when the mouse motion is large. However, the X server doesn't do that: even a single pixel of motion will cause it to power your monitor back on (or prevent your monitor from powering down in the first place.)
The only way to fix this would be to modify the X server to do what XScreenSaver does, and ignore small mouse motions for power-management idle-detection purposes.
The short answer is, for security reasons. The unlock dialog is implemented using raw Xlib because it would be very difficult to implement it using a GUI toolkit and still have xscreensaver be secure. More technical details can be found on the On Toolkits page.
Probably you are not running xscreensaver at all, but but are running "gnome-screensaver" instead. You should stop.
XScreenSaver is secure, stable, and mature; whereas gnome-screensaver is bug-ridden, unreliable, and an ongoing security disaster (for all the reasons outlined in the On Toolkits page).
Gnome-screensaver was created in 2005 by people who thought it was a better idea to rewrite all of xscreensaver from scratch instead of sending me patches for the changes they desired in xscreensaver itself.
Then in 2013, Ubuntu Unity re-wrote the screen saver engine from scratch again, introducing numerous security holes that would be hilarious if they weren't so sad.
The only sensible (and secure) way to use a screen saver under GNOME is to turn off gnome-screensaver, and use xscreensaver instead. How you go about this is explained in the "Using GNOME" section of the xscreensaver manual.
Probably you are not running xscreensaver at all, but but are running "kscreensaver" instead. You should stop.
KDE suffers from the same brain damage as GNOME, above.
The only sensible (and secure) way to use a screen saver under KDE is to turn off KDE's built-in screen saver, and use xscreensaver instead. How you go about this is explained in the "Using KDE" section of the xscreensaver manual.
The file "README.hacking" in the xscreensaver source distribution contains some helpful hints.
If you come up with anything, send it to me! If it's good, I'd love to include it in the xscreensaver distribution.