betterlockscreen: Practical Lock Screen Tool

What is betterlockscreen?

A lightweight lock screen utility for Linux that focuses on simplicity and minimalism. It supports locking, changing the background image, and small text customizations.

Quick start: common tasks

  • Lock the screen with default settings:
betterlockscreen -l
  • Update the lock screen background image:
betterlockscreen -u /path/to/image.png
  • Lock with custom text displayed on the lock screen:
betterlockscreen -l pixel --text "Locked by you"
  • Lock with a specific monitor off timeout in seconds:
betterlockscreen --off 5 -l

Note: The command uses curly braces in the help examples in the TLDR page, but in practice you can omit them and pass flags directly as shown above.

Practical usage tips

  • Always use absolute paths for images to avoid running into not-found errors when the lock screen starts.
  • If you have multiple monitors, ensure your background image works on all displays or provide a suitable single image that looks good on your primary monitor.
  • If the lock screen doesn’t appear or you see a black screen, check that your display server (Xorg vs Wayland) is compatible with betterlockscreen. It’s primarily tested with Xorg.
  • If the background doesn’t update, confirm the image file is readable by your user and that the image format is supported (PNG/JPEG commonly).

Common pitfalls and fixes

  • Pitfall: The image path is wrong or inaccessible at lock time.
    • Fix: Use an absolute path and ensure permissions allow reading by your user.
  • Pitfall: Lock shows a blank screen or no text.
    • Fix: Verify you’re running an Xorg session, and try running with -l again after logging out of a session.
  • Pitfall: Background image appears stretched or cropped oddly on a multi-monitor setup.
    • Fix: Prepare a background image that looks good on your primary monitor, or crop to your display’s resolution.

Customization options you might want

  • Custom text on the lock screen:
betterlockscreen -l pixel --text "Secure area - DO NOT ENTER"
  • Lock timeout for off state (for laptops with a lid switch):
betterlockscreen --off 10 -l

Under the hood: how it works (high level)

  • betterlockscreen integrates with your session to draw a fullscreen window with the chosen background and optional text, then waits for a valid unlock action.
  • It respects your current user permissions and tries to be non-intrusive to your desktop environment.

Troubleshooting quick checklist

  • Is the tool installed and executable?
  • Are you in a compatible session (Xorg vs Wayland)?
  • Is the background image accessible and valid?
  • Do you have sufficient permissions to lock the screen in your current session?

Further reading

See Also