XScreenSaver FAQ


These FAQs apply to the X11 version of XScreenSaver (Linux, BSD, etc.)

Please also read the manual.

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.

If you think you have found a bug, please let me know! The Bugs page explains how to submit a useful bug report. But the very first thing you should do is try the latest version to see if the bug is already fixed. Particularly if you are not yet using version 6.

Depending on your distro, the latest version might not be easily available to you. If that's the case, that means your distro sucks. You can always download the source and compile it yourself.


  1. It keeps asking me to upgrade but my distro doesn't have a newer version.
  2. How do I make XScreenSaver show a slideshow of images?
  3. How do I make XScreenSaver play a video clip?
  4. I used to be able to start typing my password before the unlock dialog had appeared, but now I have to wait for the prompt.
  5. Where does the random text come from?
  6. How do I run a particular program when the screen blanks/unblanks?
  7. You crashed my X server! You bastard!
  8. The screensaver is not noticing my mouse wheel, and blanks while I'm doomscrolling!
  9. The screen never blanks, or blanks and then unblanks right away.
  10. The screen blanks, but sometimes (but not always) my monitor doesn't go into power-saving mode.
  11. The OOM-killer killed XScreenSaver and my screen unlocked!
  12. Programs sometimes pop up dialog boxes over the screen saver while my display is locked, and I wish they didn't.
  13. Shouldn't XScreenSaver disable Ctrl-Alt-Backspace while the screen is locked?
  14. How do I unlock my screen with RFID or NFC or a fingerprint reader or retina scanner or something?
  15. The demo that's running right now is cool, how do I find out which one it is?
  16. When XScreenSaver kicks in, my machine gets slow. Is there a way to tell it to not run graphics demos?
  17. How do I prevent XScreenSaver from blanking the screen when I'm watching movies on my computer?
  18. I opened my laptop lid and the screen hadn't locked!
  19. The manual says that XScreenSaver will stop running graphics demos when my monitor goes into power-saving mode, but it doesn't. Why?
  20. The unlock dialog is funny looking, why not use GTK?
  21. I'm running GNOME or KDE, and everything's broken! What's wrong?
  22. When I'm logged in as root, XScreenSaver won't lock my screen!
  23. Some pedantic jerk told me that screen savers aren't really "necessary" any more?
  24. I'm just learning X, and I want to write a screensaver. Where should I start?



  1. It keeps asking me to upgrade but my distro doesn't have a newer version.

    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 / Fedora / 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.


  2. How do I make XScreenSaver show a slideshow of images?

    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 options for displaying slideshows on ancient 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, something like:

         default-n:  chbg -xscreensaver -randomize       \
                          -windowid $XSCREENSAVER_WINDOW \
                          -interval 0.30                 \
                          -R $HOME/Pictures/           \n\
                                                         \
         default-n:  xv -root -rmode 5 -random           \
                        -viewonly -wloop -wait 30        \
                        $HOME/Pictures/*.jpg       \n\


  3. How do I make XScreenSaver play a video clip?

    Install mpv and add something like the following to the "programs" preference in your .xscreensaver file:

         "Movies"  mpv --really-quiet --no-audio --fs --loop=inf  \
                       --no-stop-screensaver --shuffle            \
                       --wid=$XSCREENSAVER_WINDOW                 \
                       $HOME/Videos/poop.mp4                    \n\
    Or, point it at an .m3u file instead: a text file listing your video files, one per line.


  4. I used to be able to start typing my password before the unlock dialog had appeared, but now I have to wait for the prompt.

    This is an inevitable consequence of the new security model introduced in XScreenSaver 6.00. The old behavior will not be returning, so get used to clicking the mouse or tapping "Shift" before you start typing your password.

    Just typing blindly had always been bad opsec anyway: if the screen was only blanked but not locked, you probably would have accidentally typed part of your password into another window.


  5. Where does the random text come from?

    See the 'Advanced' tab on the XScreenSaver control panel.


  6. How do I run a particular program when the screen blanks/unblanks?

    You can do that using xscreensaver-command --watch. See the xscreensaver-command manual for an example.


  7. You crashed my X server! You bastard!

    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 client -- but probably not.

    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 OpenGL screensavers, since those are the ones that exercise your GPU. 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.

    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.


  8. The screensaver is not noticing my mouse wheel, and blanks while I'm doomscrolling!

    Upgrade to XScreenSaver 6.00 or newer.


  9. The screen never blanks, or blanks and then unblanks right away.

    The first possibility is that your mouse is getting bumped. Cats, trucks, doors, and earthquakes are likely culprits.

    Another possibility is that some other program on your system is explicitly instructing XScreenSaver to deactivate, or has requested that the screen never blank. Web browsers and movie players do this while playing video, but some of them will leave blanking inhibited forever if they crash. So if you had a video player crash, try killing and restarting the xscreensaver-systemd helper program and see if that fixes it.

    If that doesn't solve it, restart xscreensaver with -verbose (see the "Reporting Bugs" page) and see if it is reporting "user is active" or the receipt of "deactivate" events.


  10. The screen blanks, but sometimes (but not always) my monitor doesn't go into power-saving mode.

    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.


  11. The OOM-killer killed XScreenSaver and my screen unlocked!

    Linux systems have an out-of-memory killer that will start killing random processes in low-memory situations. You'd think it would pick the process using the most memory, but most of the time it seems to pick the process that would be most comically inconvenient, such as your screen locker, or crond.

    If XScreenSaver is installed setuid, it attempts to tell the OOM-killer to leave it alone. That may or may not work.

    You can disable the OOM-killer entirely by doing:


  12. Programs sometimes pop up dialog boxes over the screen saver while my display is locked, and I wish they didn't.

    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 may be 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 changing those applications to use normal windows instead.


  13. Shouldn't XScreenSaver disable Ctrl-Alt-Backspace while the screen is locked?

    Yes, it should. Unfortunately, that's not possible with any version 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. There are numerous backdoor keystrokes that your distro may have "helpfully" enabled on your system. They are described in the "Security" section of the manual.


  14. How do I unlock my screen with RFID or NFC or a fingerprint reader or retina scanner or something?

    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.


  15. The demo that's running right now is cool, how do I find out which one it is?

    Run the xscreensaver-settings 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.


  16. When XScreenSaver kicks in, my machine gets slow. Is there a way to tell it to not run graphics demos?

    You can still blank and/or lock your screen, while denying yourself the pleasure of graphical screen savers, by running xscreensaver-settings and selecting "Blank Screen Only" from the "Mode" option menu.

    The real problem is almost certainly that your X server is not making use of your GPU. Fix that instead.


  17. How do I prevent XScreenSaver from blanking the screen when I'm watching movies on my computer?

    This happens automatically with recent versions of XScreenSaver and all of: Firefox, Chrome, Chromium, MPV and VLC. You need XScreenSaver 5.45 or later, and systemd 221 or later or elogind.

    If that's not working, and you are unable to upgrade:

    If you are trying to use XFCE's "Presentation Mode"... don't. It breaks everything. Use XScreenSaver's "Disable Screen Saver" mode instead.


  18. I opened my laptop lid and the screen hadn't locked!

    Recent versions of XScreenSaver automatically lock on suspend. You need XScreenSaver 5.43 or later, and systemd 221 or later or elogind.

    If that's not working, and you are unable to upgrade, then the short answer is, "lock your screen before closing the lid".

    The longer answer is that what is happening is this:

    1. Your screen is not locked.
    2. You close the lid.
    3. The CPU halts.
    4. Hours pass.
    5. You open the lid.
    6. The CPU starts running again.
    7. The X server re-draws the previous screen contents.
    8. Oh hey, the screen is still not locked, because the machine is just like it was before, except that now the disk is thrashing because everything is trying to run at once.
    9. Eventually, the XScreenSaver process is scheduled again, and notices that the wall-clock has jumped by hours.
    10. Then XScreenSaver says "oh shit!" and locks the screen.

    What you are experiencing is the gap between steps 7 and 10.

    XScreenSaver's systemd integration fixes this by arranging for "xscreensaver-command --suspend" to be run between steps 2 and 3.


  19. The manual says that XScreenSaver will stop running graphics demos when my monitor goes into power-saving mode, but it doesn't. Why?

    This happens automatically if your X server supports the DPMS extension. It may take a minute to notice.

    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.


  20. The unlock dialog is funny looking, why not use GTK?

    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.

    The look of that dialog is somewhat customizable. See the "Theme" menu in xscreensaver-settings. You can add new themes by editing the XScreenSaver.ad app-defaults file.


  21. I'm running GNOME or KDE, and everything's broken! What's wrong?

    Probably you are not running XScreenSaver at all, but but are running "gnome-screensaver" or "kscreensaver" 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.

    In 2011 or so, "gnome-screensaver" was forked and renamed as both "mate-screensaver" and "cinnamon-screensaver", re-arranging the deck chairs while fixing none of their fundamental design problems.

    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 way to securely lock your screen under X11 is to turn off gnome-screensaver, mate-screensaver, cinnamon-screensaver, etc. and use XScreenSaver instead. How you go about this is explained in the "Installing on GNOME" section of the XScreenSaver manual.

    Remember:


  22. When I'm logged in as root, XScreenSaver won't lock my screen!

    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.


  23. Some pedantic jerk told me that screen savers aren't really "necessary" any more?

    How terrible it must be for them to have no soul. What has broken in their life to make them hate joy?


  24. I'm just learning to program X, and I want to write an XScreenSaver module. Where should I start?

    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.