Go to file
Aditya Kumar 8652b68c40 resolved merge conflict 2022-03-09 07:08:01 +05:30
.github Part of #232 - add issue-template for bug, feature-request and also basic pr-template 2021-10-11 17:49:13 +02:00
examples Added quiet-mode (#288) 2021-10-11 17:48:56 +02:00
CONTRIBUTING.md Copyright year 2022, update repository URL 2022-01-14 14:39:00 +01:00
LICENSE Copyright year 2022, update repository URL 2022-01-14 14:39:00 +01:00
README.md update README 2022-02-21 10:58:58 +05:30
betterlockscreen resolved merge conflict 2022-03-09 07:08:01 +05:30
install.sh update install script to fetch and install 2022-02-21 10:58:00 +05:30
shell.nix nix-shell: add bash5 for testing (#209) 2021-05-16 19:22:24 +02:00



fast and sweet looking lockscreen for linux systems with effects and OpenRC support!

Forked from betterlockscreen/betterlockscreen


Table of Contents


Most of i3lock wrapper-scripts out there take an image, add some effect(s) then lock with the modified image as locker-background. Overall experience doesn't feel natural given delay of 2-3 seconds.

Who would like a delay of 2-3 seconds while locking screen?

So Betterlockscreen was my attempt to solve this problem, as we dont need to change lockscreen background frequently this script caches images with effect so overall experience is simple and as fast as native i3lock.

How it works

The script takes a directory or image, adds various effects and caches the images in special directory. Those cached images will be used as locker-background depending on configuration provided by user.

System Requirements

Note: Make sure your system has all dependencies satisfied


Installation Script

Clone the repo and run the script. The script is very simple and takes two parameters:

  • <install-mode>: (string) 'user' installs to '~/.local/bin/', 'system' installs to '/usr/local/bin'
  • [<version>]: (string) defaults to local, which will install from the local copy of the repo. Use 'latest', which will discard any chnage made locally and update the repo

For system-installation:

bash install.sh system

For user-installation:

bash install.sh user

Manual Installation

Clone the repo and copy betterlockscreen to the relevant directory. Make sure you have dependenncies installed. See System Requirements above.


You can customize betterlockscreen for your needs, copy the config file from the examples-directory to ~/.config/betterlockscreenrc and edit it accordingly.

If no configuration-file is found, then the default configurations (which is equal to the example but currently hardcoded) will be used.


Run betterlockscreen and point it to either a directory (betterlockscreen -u "path/to/dir") or an image (betterlockscreen -u "/path/to/img.jpg") and that's all. betterlockscreen will change update its cache with image you provided.

Usage: betterlockscreen [-u <PATH>] [-l <EFFECT>] [-w <EFFECT>]

  -u --update <PATH>
      Update lock screen image

  -l --lock <EFFECT>
      Lock screen with cached image

  -w --wall <EFFECT>
      Set wallpaper with cached image

Additional arguments:

  --display <N>
      Set display to draw loginbox

      Scale image to span multiple displays

  --off <N>
      Turn display off after N seconds

      List of effects to apply

  -- <ARGS>
      Pass following arguments to i3lock

Effects arguments:

  --dim <N>
      Dim image N percent (0-100)

  --blur <N>
      Blur image N amount (0.0-1.0)

  --pixel <N,N>
      Pixelate image with N shrink and N grow (unsupported)

  --color <HEX>
      Solid color background with HEX


  1. Update image cache with random image betterlockscreen -u ~/Wallpapers

  2. Update image cache with only dim and pixel effects betterlockscreen -u ~/Wallpapers/image.png --fx dim,pixel

  3. Update image cache with random image, multiple monitors, login on 1, spanning betterlockscreen -u ~/Wallpapers/Dual/ --display 1 --span

  4. Update image cache with solid background only (ignore errors) betterlockscreen -u . --fx color --color 5833ff

  5. Update image cache with different background images betterlockscreen -u ~/Wallpapers/image1.png -u ~/Wallpapers/image2.png

  6. Lock screen with blur effect betterlockscreen --lock blur

  7. Lock screen with multiple monitors, spanning betterlockscreen -l dimblur --display 1 --span


Add this line to .xinitrc.

# set desktop background with custom effect
betterlockscreen -w dim

# Alternative (set last used background)
source ~/.fehbg


Add this line to ~/.config/i3/config

# set desktop background with custom effect
exec --no-startup-id betterlockscreen -w dim

# Alternative (set last used background)
exec --no-startup-id source ~/.fehbg


To lockscreen using keyboard shortcut


Add this line to your ~/.config/i3/config

bindsym $mod+shift+x exec betterlockscreen -l dim


Add this line to your ~/.config/sxhkd/sxhkdrc

# lockscreen
alt + shift + x
    betterlockscreen -l dim


Please see CONTRIBUTING.md.


Betterlockscreen is under MIT license.

Feel free to use and distribute

  • Hat tip to anyone who's code was used
  • Thanks to those who contributed to make it better
  • Inspiration - r/unixporn