{"id":13554596,"url":"https://github.com/betterlockscreen/betterlockscreen","last_synced_at":"2025-05-15T00:06:49.947Z","repository":{"id":37464566,"uuid":"113487002","full_name":"betterlockscreen/betterlockscreen","owner":"betterlockscreen","description":"🍀 sweet looking lockscreen for linux system","archived":false,"fork":false,"pushed_at":"2024-08-03T18:27:57.000Z","size":8106,"stargazers_count":2529,"open_issues_count":36,"forks_count":178,"subscribers_count":20,"default_branch":"next","last_synced_at":"2025-04-11T10:17:01.445Z","etag":null,"topics":["betterlockscreen","feh","hacktoberfest","i3lock","i3lock-color","i3wm","linux","lockscreen","lockscreen-background"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/betterlockscreen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-07T18:50:10.000Z","updated_at":"2025-04-08T20:49:28.000Z","dependencies_parsed_at":"2024-01-14T04:34:53.360Z","dependency_job_id":"e69846ca-cf1e-492a-aaad-7186142a6f01","html_url":"https://github.com/betterlockscreen/betterlockscreen","commit_stats":null,"previous_names":["pavanjadhaw/betterlockscreen"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betterlockscreen%2Fbetterlockscreen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betterlockscreen%2Fbetterlockscreen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betterlockscreen%2Fbetterlockscreen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betterlockscreen%2Fbetterlockscreen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/betterlockscreen","download_url":"https://codeload.github.com/betterlockscreen/betterlockscreen/tar.gz/refs/heads/next","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249198,"owners_count":22039029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["betterlockscreen","feh","hacktoberfest","i3lock","i3lock-color","i3wm","linux","lockscreen","lockscreen-background"],"created_at":"2024-08-01T12:02:50.994Z","updated_at":"2025-05-15T00:06:49.663Z","avatar_url":"https://github.com/betterlockscreen.png","language":"Shell","readme":"\u003cimg src=\"./logo.svg\" height=\"200\" alt=\"BLS-Logo\" /\u003e\n\n# Betterlockscreen\n\u003e fast and sweet looking lockscreen for linux systems with effects!\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/releases\"\u003e\u003cimg alt=\"GitHub release (latest by date including pre-releases)\" src=\"https://img.shields.io/github/v/release/betterlockscreen/betterlockscreen?include_prereleases\u0026label=latest\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/releases\"\u003e\u003cimg alt=\"GitHub release (latest by date)\" src=\"https://img.shields.io/github/v/release/betterlockscreen/betterlockscreen?label=Stable\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/actions/workflows/main.yml?query=branch%3Amain\"\u003e\u003cimg alt=\"GitHub Workflow Status (main)\" src=\"https://img.shields.io/github/actions/workflow/status/betterlockscreen/betterlockscreen/main.yml?branch=main\u0026label=main\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/actions/workflows/main.yml?query=branch%3Anext\"\u003e\u003cimg alt=\"GitHub Workflow Status (next)\" src=\"https://img.shields.io/github/actions/workflow/status/betterlockscreen/betterlockscreen/main.yml?branch=next\u0026label=next\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/milestone/2\"\u003e\u003cimg alt=\"GitHub milestone\" src=\"https://img.shields.io/github/milestones/progress/betterlockscreen/betterlockscreen/2?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/compare/v4.3.0...next\"\u003e\u003cimg alt=\"GitHub commits since latest release (by date) for a branch\" src=\"https://img.shields.io/github/commits-since/betterlockscreen/betterlockscreen/v4.3.0/next?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/betterlockscreen/betterlockscreen.svg?style=for-the-badge\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003eYou want to support us?\u003c/h2\u003e\n\n  \u003cdiv\u003e\n    \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/discussions/366\"\u003eWe are searching a new Maintainer!\u003c/a\u003e\n  \u003c/div\u003e\n\n  \u003cbr /\u003e\n  \n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/stargazers\"\u003e\u003cimg alt=\"GitHub Repo stars\" src=\"https://img.shields.io/github/stars/betterlockscreen/betterlockscreen?style=social\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/betterlockscreen/betterlockscreen/fork\"\u003e\u003cimg alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/betterlockscreen/betterlockscreen?style=social\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.codetriage.com/betterlockscreen/betterlockscreen\"\u003e\u003cimg src=\"https://www.codetriage.com/betterlockscreen/betterlockscreen/badges/users.svg\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\n![scrot2](https://github.com/pavanjadhaw/betterlockscreen.demo/raw/master/scrots/scrot2.png 'scrot2.png')\n\u003cbr /\u003e\n\n## Table of Contents\n\n- [About](#about)\n- [How it works](#how-it-works)\n- [System Requirements](#system-requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Background](#background)\n- [Keybinding](#keybindings)\n- [Lockscreen on sleep/suspend with systemd](#systemd)\n\n## About\n\nMost 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.\n\n\u003e Who would like a delay of 2-3 seconds while locking screen?\n\nSo 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.\n\n## How it works\n\nThe 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.\n\n## System Requirements\n\n* [i3lock-color](https://github.com/Raymo111/i3lock-color) `\u003e= 2.13.c.3`\n* [ImageMagick](https://imagemagick.org/)\n* [bc](https://www.gnu.org/software/bc/)\n* xdpyinfo, xrandr, xrdb and xset from [X.Org](https://www.x.org/)\n* (Optional) [Dunst](https://dunst-project.org/)\n* (Optional) [feh](https://feh.finalrewind.org/) for wallpaper-functionality\n\n\u003e Note: Make sure your system has all dependencies satisfied\n\n## Installation\n### Package Manager\n\n\u003ca href=\"https://repology.org/project/betterlockscreen\"\u003e\n  \u003cimg src=\"https://repology.org/badge/vertical-allrepos/betterlockscreen.svg\" alt=\"Packaging status\" align=\"right\"\u003e\n\u003c/a\u003e\n\nBetterlockscreen is available via package manager on some linux-distributions, if you miss your favorite one you can follow along with our [installation-script](#installation-script) or [manual-installation](#manual-installation).\n\nIf you are using **Arch Linux**, you can install the AUR package\n[betterlockscreen](https://aur.archlinux.org/packages/betterlockscreen/) to get the latest\nversion, or [betterlockscreen-git](https://aur.archlinux.org/packages/betterlockscreen-git/) for the most up-to-date (unstable) changes.\n\nIf you are using **Gentoo Linux**, you can install `betterlockscreen` from Gentoo's [GURU overlay](https://wiki.gentoo.org/wiki/Project:GURU) using `emerge x11-misc/betterlockscreen`.\n\nIf you are using **NixOS**, [betterlockscreen](https://search.nixos.org/packages?query=betterlockscreen) is available in both the [stable](https://github.com/NixOS/nixpkgs/blob/nixos-21.05/pkgs/misc/screensavers/betterlockscreen/default.nix) and [unstable](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/misc/screensavers/betterlockscreen/default.nix) channels and can be installed using `nix-env -iA nixos.betterlockscreen`.\n\nIf you are using **Void Linux**, you can install [betterlockscreen](https://github.com/void-linux/void-packages/blob/master/srcpkgs/betterlockscreen/template) using `xbps-install -S betterlockscreen`.\n\n### Installation Script\n\nWe have created an automatic [install-script](https://github.com/betterlockscreen/betterlockscreen/blob/main/install.sh) for Betterlockscreen. The script is very simple and takes three parameters:\n  * `\u003cinstall-mode\u003e`: (string) 'user' installs to '~/.local/bin/', 'system' installs to '/usr/local/bin'\n  * `[\u003cversion\u003e]`: (string) defaults to 'latest' which will determinate the latest tag from git or specified branch/tag\n  * `[\u003csystemd-service\u003e]`: (boolean) defaults to 'false' - Whether to copy and enable system-service.\n\nFor system-installation:\n```sh\nwget https://raw.githubusercontent.com/betterlockscreen/betterlockscreen/main/install.sh -O - -q | sudo bash -s system\n```\n\nFor user-installation:\n```sh\nwget https://raw.githubusercontent.com/betterlockscreen/betterlockscreen/main/install.sh -O - -q | bash -s user\n```\n\n### Manual Installation\n\nỲou can download the latest release [here](https://github.com/betterlockscreen/betterlockscreen/releases), please ensure to fullfill the [system-requirements](#system-requirements)!\n\nYou will need to copy \"betterlockscreen\" to you desired binary-directory, if you want to use the systemd-service you will need to copy the service-file from \"system/\" to the desired location on your system.\n\nExample (Ubuntu):\n```sh\nwget https://github.com/betterlockscreen/betterlockscreen/archive/refs/heads/main.zip\nunzip main.zip\n\ncd betterlockscreen-main/\nchmod u+x betterlockscreen\ncp betterlockscreen /usr/local/bin/\n\ncp system/betterlockscreen@.service /usr/lib/systemd/system/\nsystemctl enable betterlockscreen@$USER\n```\n\n## Configuration\n\nYou can customize Betterlockscreen for your needs, copy the config file from the examples-directory to the user-configuration directory `~/.config/betterlockscreen/` and edit it accordingly.\n\n```sh\nmkdir -p ~/.config/betterlockscreen/\ncp /usr/share/doc/betterlockscreen/examples/betterlockscreenrc ~/.config/betterlockscreen/\n```\n\nIf no configuration-file is found, then the default configurations (which is equal to the example but hardcoded) will be used.\n\n### Custom script's on pre/post-lock\nIf present in user-configuration directory (see above) the \"custom-(pre|post).sh\" gets sourced at the appropriate time. This can be used to pause notification (not needed for dunst!), switch keyboard-layout on pre/post-lock etc.\n\n## Usage\n\nRun `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.\n\n```sh\nUsage: betterlockscreen [-u \u003cPATH\u003e] [-l \u003cEFFECT\u003e] [-w \u003cEFFECT\u003e]\n\n  -u --update \u003cPATH\u003e\n      Update lock screen image\n\n  -l --lock \u003cEFFECT\u003e\n      Lock screen with cached image\n\n  -w --wall \u003cEFFECT\u003e\n      Set wallpaper with cached image\n\nAdditional arguments:\n\n  --display \u003cN\u003e\n      Set display to draw loginbox\n\n  --span\n      Scale image to span multiple displays\n\n  --off \u003cN\u003e\n      Turn display off after N seconds\n\n  --fx \u003cEFFECT,EFFECT,EFFECT\u003e\n      List of effects to apply\n\n  -- \u003cARGS\u003e\n      Pass following arguments to i3lock\n\nEffects arguments:\n\n  --dim \u003cN\u003e\n      Dim image N percent (0-100)\n\n  --blur \u003cN\u003e\n      Blur image N amount (0.0-1.0)\n\n  --pixel \u003cN,N\u003e\n      Pixelate image with N shrink and N grow (unsupported)\n\n  --color \u003cHEX\u003e\n      Solid color background with HEX\n```\n\n#### Examples\n1. Update image cache with random image\n`betterlockscreen -u ~/Wallpapers`\n\n2. Update image cache with only dim and pixel effects\n`betterlockscreen -u ~/Wallpapers/image.png --fx dim,pixel`\n\n3. Update image cache with random image, multiple monitors, login on 1, spanning\n`betterlockscreen -u ~/Wallpapers/Dual/ --display 1 --span`\n\n4. Update image cache with solid background only (ignore errors)\n`betterlockscreen -u . --fx color --color 5833ff`\n\n5. Update image cache with different background images\n`betterlockscreen -u ~/Wallpapers/image1.png -u ~/Wallpapers/image2.png`\n\n6. Lock screen with blur effect\n`betterlockscreen --lock blur`\n\n7. Lock screen with multiple monitors, spanning\n`betterlockscreen -l dimblur --display 1 --span`\n\n#### AwesomeWM - naughty\nIt has been discovered that the integrated notification-system \"naughty\" which is included and enabled by default, causes issue with dunst when running parallel.\n\nIf dunst is not installed, there should be no issue, if dunst is installed (even not running) our integration will try to pause dunst on lock/resume on unlock, which lead to a DBus reply timeout.\n\nTo fix this, please add the following line to your `rc.lua`:\n```\npackage.loaded[\"naughty.dbus\"] = {}\n```\n\nSource: #284 (thanks to @nullbyto), https://github.com/awesomeWM/awesome/issues/1285\n\n## Background\n\nAdd this line to `.xinitrc`.\n\n```sh\n# set desktop background with custom effect\nbetterlockscreen -w dim\n\n# Alternative (set last used background)\nsource ~/.fehbg\n```\n\n### i3wm\n\nAdd this line to `~/.config/i3/config`\n\n```sh\n# set desktop background with custom effect\nexec --no-startup-id betterlockscreen -w dim\n\n# Alternative (set last used background)\nexec --no-startup-id source ~/.fehbg\n```\n\n## Keybindings\n\nTo lockscreen using keyboard shortcut\n\n### i3wm\n\nAdd this line to your `~/.config/i3/config`\n\n```sh\nbindsym $mod+shift+x exec betterlockscreen -l dim\n```\n\n### bspwm\n\nAdd this line to your `~/.config/sxhkd/sxhkdrc`\n\n```sh\n# lockscreen\nalt + shift + x\n    betterlockscreen -l dim\n```\n\n\u003ch2 id=\"systemd\"\u003eSystemd-Service: Lockscreen after sleep/suspend\u003c/h2\u003e\n\n```sh\n# move service file to proper dir (the aur package does this for you)\ncp betterlockscreen@.service /usr/lib/systemd/system/\n\n# enable systemd service\nsystemctl enable betterlockscreen@$USER\n\n# disable systemd service\nsystemctl disable betterlockscreen@$USER\n\n# Note: Now you can call systemctl suspend to suspend your system\n# and betterlockscreen service will be activated\n# so when your system wakes your screen will be locked.\n```\n\n**Hint:** The systemd-unit expects betterlockscreen to be installed in \"/usr/local/bin\", so maybe you want to check or change this!\n\nResources and more informations:\n * https://gist.github.com/Raymo111/91ffd256b7aca6a85e8a99d6331d3b7b\n * https://github.com/Raymo111/i3lock-color/issues/174#issuecomment-687149213\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nBetterlockscreen is under [MIT](https://github.com/betterlockscreen/betterlockscreen/blob/main/LICENSE) license.\n\n### Feel free to use and distribute\n\n- Hat tip to anyone who's code was used\n- Thanks to those who contributed to make it better\n- Inspiration - [r/unixporn](https://www.reddit.com/r/unixporn)\n\n### Supported by\n\u003ca href=\"https://jb.gg/OpenSourceSupport\"\u003e\n  \u003cimg src=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png\" height=\"100\" alt=\"JetBrains Logo (Main) logo\" /\u003e\n\u003c/a\u003e\n","funding_links":[],"categories":["Shell","Requirements"],"sub_categories":["widgets"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterlockscreen%2Fbetterlockscreen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetterlockscreen%2Fbetterlockscreen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterlockscreen%2Fbetterlockscreen/lists"}