betterlockscreen

Lock the screen

$ betterlockscreen [[-l|--lock]]

$ betterlockscreen [[-u|--update]] [path/to/image.png]

$ betterlockscreen [[-l|--lock]] pixel --text "[custom lock screen text]"

$ betterlockscreen --off [5] [[-l|--lock]]

betterlockscreen [OPTION]...
Update: betterlockscreen -u|--update IMAGE [options]
Lock: betterlockscreen -l|--lock|-s|--suspend|-r|--leave [options]

-h, --help
    Display help and exit.

-V, --version
    Output version information.

-u, --update IMAGE
    Update lockscreen image cache from IMAGE file.

-l, --lock
    Lock screen using cached image.

-s, --suspend
    Lock screen and suspend system.

-r, --leave
    Unlock/leave the lockscreen.

--display DISPLAY
    X11 display to grab screenshot from.

--off
    Turn off all displays on lock.

--blur [BLUR]
    Apply Gaussian blur (default 1.0, 0-10 range).

--dim [DIM]
    Dim image brightness (default 0.05, 0-1 range).

--span
    Span image across all monitors.

--tile
    Tile image to fill monitors.

--effects PATH
    Path to effects.conf for custom effects.

--greeter
    Enable centered greeter with time/date.

--inverting
    Apply inverting color effect.

--inverting-line
    Apply inverting line effect.

--greeter-text TEXT
    Custom greeter text (default user@host).

--greeter-align ALIGN
    Greeter alignment: left/center/right.

--time-font FONT
    Font for time display.

--time-size SIZE
    Font size for time.

--time-color COLOR
    Color for time (hex or name).

--date-font FONT
    Font for date display.

--date-size SIZE
    Font size for date.

--date-color COLOR
    Color for date.

--greeter-font FONT
    Font for greeter text.

--greeter-size SIZE
    Font size for greeter.

--greeter-color COLOR
    Color for greeter.

--bg-color COLOR
    Fallback background color.

--i3lock-flags FLAGS
    Additional flags passed to i3lock.

--swaylock-flags FLAGS
    Additional flags passed to swaylock.

Betterlockscreen is a lightweight, script-based utility that enhances screen locking on Linux, primarily for i3wm and Sway (Wayland). It captures a screenshot of the current desktop, applies customizable effects like Gaussian blur, dimming, spanning across monitors, or tiling, and sets it as the background for i3lock or swaylock. This creates a modern, blurred wallpaper lockscreen that's both secure and aesthetically pleasing.

Workflow: First, update the image cache with betterlockscreen -u /path/to/image.jpg and options for effects. The processed image is saved in ~/.cache/betterlockscreen/ for instant recall. Then, invoke betterlockscreen -l to lock, -s to lock+suspend, or -r to unlock. It supports multi-monitor setups, custom greeters with time/date display, font/color tweaks, and advanced effects via config files.

Key advantages include low overhead, high customizability without forking i3lock, and Wayland compatibility. Ideal for ricing enthusiasts. Requires i3lock, swaylock, or swaylock-effects for full features. Commonly bound to Mod+l in i3 config or used with xss-lock/swayidle for auto-locking.

Requires i3lock, swaylock, or swaylock-effects installed. Caches images in ~/.cache/betterlockscreen/ (needs write access). X11-focused; Wayland needs grim/slurp for grabs. Effects may require ImageMagick. Not a standalone locker—relies on underlying tools.

AUR (Arch): yay -S betterlockscreen. GitHub: Clone repo, make install. Dependencies: bash, convert (ImageMagick), i3lock/swaylock.

Bind in i3: bindsym $mod+l exec betterlockscreen -l. Auto-lock: xss-lock -- betterlockscreen -l. Customize effects in ~/.config/betterlockscreen/effects.conf.

Add to i3 config: exec_always --no-startup-id betterlockscreen -u wallpaper --span --blur.

Created by Eros Zsolt (aswild) in 2018 as a GitHub project to improve i3lock visuals. Gained popularity in r/unixporn for ricing. Added Wayland/swaylock support in 2020. Actively maintained with v3+ featuring swayidle integration, effects.conf, and greeter enhancements. Available in AUR, Nixpkgs.

i3lock(1), swaylock(1), xss-lock(1), swayidle(1), ImageMagick(1)