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.

  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 of 6.15 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 you can't find version 6.15 in any of those places, then you'll have to build from source.

  2. My distro switched me to Wayland and now nothing works.

    Yes, it is an absolute disaster. The XScreenSaver manual explains why XScreenSaver does not work properly under Wayland, and contains instructions for switching back from Wayland to X11. (For as long as that continues to work.)

    XScreenSaver 6.11 and later contain preliminary support for Wayland, but it is limited: it does not work under GNOME, and locking is not implemented.

    I have been warning about this problem since 2021, and wrote in some detail about the technical issues on my blog in 2023. Wayland could be improved to allow screen savers to continue to exist, but it appears that the Wayland developers have no interest in fixing this regression.

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

    Just select "GLSlideshow" in the XScreenSaver control panel, and enter the directory (or RSS URL) where your images live on the "Advanced" tab. It displays a sequence of images, slowly panning and zooming through them, and fading smoothly from one image to the next.

    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 you try to use a third-party program to display images instead of just using GLSlideshow, you are setting yourself up for frustration and disappointment. So probably don't try to do that.

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

    Probably you can't. There used to be a way to do it with MPV, but they broke that.

  5. 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 in 2021. 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.

  6. Where does the random text come from?

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

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

  8. 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.

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

    Upgrade to XScreenSaver 6.00 or newer (released in 2021).

  10. 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 --log (see the "Reporting Bugs" page) and see if it is reporting "user is active" or the receipt of "deactivate" events.

  11. 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, but that will never happen.

  12. 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:

    sudo sh -c 'echo 2 > /proc/sys/vm/overcommit_memory'
    sudo sh -c 'echo vm.overcommit_memory = 2 >> /etc/sysctl.conf'

  13. This is a bug in your window manager and/or that application, and there is little that XScreenSaver can do about it. If this is happening it is because of one of two reasons:

    1. The window manager is placing windows on screen with XRaiseWindow, meaning, "place this window atop all others, including the screen saver." This is wrong.

      What it should be doing instead is ordering its windows using XRestackWindows, the semantics of which are, "here is the list of windows I manage, and the order in which they should be stacked." By using XRestackWindows, the window manager will never alter the stacking order of non-managed windows that are not within its remit.

    2. The application is using an OverrideRedirect window, explicitly hiding its pop-up window from the window manager. This is also wrong.

      Pop-ups, notifications, and all similar windows should be mapped as WM_TRANSIENT_FOR and/or _NET_WM_WINDOW_TYPE_DIALOG windows, as has been explained by the ICCCM and the FreeDesktop EWMH specifications for decades.

    XScreenSaver can't prevent such improperly-mapped windows from appearing on screen, but it does slightly mitigate that by raising itself above them every few minutes. The real fix is for your window manager to not allow this to happen in the first place.

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

    Yes, it should. Unfortunately, that's not possible with any version of the Xorg server. 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.

  15. 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.

  16. 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.

  17. 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.

  18. 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 and VLC. You need XScreenSaver 5.45 or later (released in 2020), and systemd 221 or later or elogind.

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

    When you want to watch a movie, fire up

    xscreensaver-settings

    and select

    Mode: Disable Screen Saver

    from the option menu, which means not to blank the screen at all. When you're done watching the movie, re-select your previous mode.

    If you're using MPV, use VLC instead.

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

  19. 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 (released in 2019), 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.

  20. 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.

  21. 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.

  22. 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:

    Once is happenstance. Twice is coincidence. Three times is enemy action. Four times is Official GNOME Policy.

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

    Don't log in as root. Proper Unix hygiene dictates that you should log in as yourself, and sudo as necessary. People who spend their day logged in as root are just begging for disaster.

  24. 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?

  25. 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.

    No contributions built with, or assisted by, LLMs or any kind of "generative AI" tools will be considered. If you didn't bother writing it, I'm not going to bother reading it. XScreenSaver is art by humans for humans.