i3lock(1)

✨ i3lock — improved screen locker ✨

okay so bestie, welcome to the i3lock(1) manual page, from the User Manuals section. this is the screen locker that ate 💅 it locks your screen, it looks however you want, and it uses PAM so it plays nice with LDAP and friends. let's get into it.

---

🌸 SYNOPSIS 🌸

i3lock [-v] [-n] [-b] [-i image.png] [-c color] [-t] [-p pointer] [-u]
[-e] [-f]

---

👑 RECOMMENDED USAGE 👑

xss-lock --transfer-sleep-lock -- i3lock --nofork

fr fr, this is the way. using xss-lock means your screen gets locked before your laptop suspends. that's the whole point.

not me using a systemd service file 😭 because that is not adequate — a systemd service file will not delay suspend until your screen is locked. so don't do that. periodt.

---

🦋 DESCRIPTION 🦋

i3lock is a simple screen locker, kinda like slock. you start it up and you get a white screen (or, like, whatever color/image you configured, you icon). you get back to your screen by entering your password. that's it. that's the vibe.

---

💖 IMPROVEMENTS 💖

• i3lock forks, so you can pair it with an alias to suspend to RAM — run i3lock && echo mem > /sys/power/state and you'll get a locked screen after your computer wakes up from suspend to RAM. slay
• you can specify either a background color or a PNG image, and it'll be displayed while your screen is locked.
• you can specify whether i3lock should bell upon a wrong password. 🔔
• i3lock uses PAM, which means it's compatible with LDAP, etc. cross-compatible queen

---

💅 OPTIONS 💅

• -v, --version — display the version of your i3lock. 🎀
• -n, --nofork — don't fork after starting.
• -b, --beep — enable beeping. but be sure to not do this when you're about to annoy other people, like when opening your laptop in a boring lecture. 🙈 please bestie, i'm begging.
• -u, --no-unlock-indicator — disable the unlock indicator. by default i3lock shows an unlock indicator after pressing keys, which gives feedback for every keypress and shows you the current PAM state (whether your password is currently being verified or whether it is wrong). lowkey useful, highkey your call.
• *-i *path, --image=path — display the given PNG image instead of a blank screen. 🖼️
• *--raw=format* — read the image given by --image as a raw image instead of PNG. the argument is the image's format, written as <width>x<height>:<pixfmt>. the supported pixel formats are: native, rgb, xrgb, rgbx, bgr, xbgr, and bgrx. the native pixel format expects a pixel as a 32-bit (4-byte) integer in the machine's native endianness, with the upper 8 bits unused; red, green and blue are stored in the remaining bits, in that order.

example:

--raw=1920x1080:rgb

you can use ImageMagick's convert(1) program to feed raw images into i3lock:

convert wallpaper.jpg RGB:- | i3lock --raw 3840x2160:rgb --image /dev/stdin

this lets you load a variety of image formats without i3lock having to support each one explicitly. big brain energy 🧠✨

• *-c *rrggbb, --color=rrggbb — turn the screen into the given color instead of white. color must be given in 3-byte format: rrggbb (i.e. ff0000 is red). 🌈
• -t, --tiling — if an image is specified (via -i) it will display the image tiled all over the screen. and if it's a multi-monitor setup, the image is visible on all screens. 🖥️🖥️
• *-p *win|default, --pointer=win|default — if you specify default, i3lock does not hide your mouse pointer. if you specify win, i3lock displays a hardcoded Windows-Pointer (thus enabling you to mess with your friends by using a screenshot of a Windows desktop as a locking-screen). 💀 iconic prank behavior, no cap.
• -e, --ignore-empty-password — when an empty password is provided by the user, do not validate it. without this option, the empty password will be provided to PAM and, if invalid, the user will have to wait a few seconds before another try. this can be useful if the XF86ScreenSaver key is used to put a laptop to sleep and bounce on resume, or if you happen to wake up your computer with the enter key. the way that enter key betrays you 😭
• -f, --show-failed-attempts — show the number of failed attempts, if any. tracking the L's, respectfully
• -k, --show-keyboard-layout — show the current keyboard layout. ⌨️
• --debug — enables debug logging.

⚠️ NOTE, BESTIE ⚠️ --debug will log the password used for authentication to stdout. the password. to stdout. be so careful with that. 🫶

---

🎀 DPMS 🎀

the -d (--dpms) option was removed from i3lock in version 2.8. there were plenty of use-cases that were not properly addressed, and plenty of bugs surrounding that feature. while features are not normally removed from i3 and its tools, we felt the need to make an exception in this case.

users who wish to explicitly enable DPMS only when their screen is locked can use a wrapper script around i3lock like the following:

#!/bin/sh
revert() {
  xset dpms 0 0 0
}
trap revert HUP INT TERM
xset +dpms dpms 5 5 5
i3lock -n
revert

the -I (--inactivity-timeout=seconds) was also removed, because it only makes sense with DPMS. gone but not forgotten 🕊️

---

🌈 SEE ALSO 🌈

• xss-lock(1) — hooks up i3lock to the systemd login manager
• convert(1) — feed a wide variety of image formats to i3lock

---

⭐ AUTHOR ⭐

Michael Stapelberg <michael+i3lock at stapelberg dot de>

---

and that's the whole page, bestie!! this one came from the Linux manual set, dated JANUARY 2012, and it's i3lock(1) all the way through. go lock that screen. 🔒💜