marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/hyprlock.md
View on GitHub<!-- source: https://wiki.hypr.land/hypr-ecosystem/user/hyprlock -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
---
weight: 50
title: hyprlock
---
[hyprlock](https://github.com/hyprwm/hyprlock) is a simple, yet fast, multi-threaded and GPU-accelerated screen locker for Hyprland.
> [!WARNING]
> If no config file is found in any of the searched paths, hyprlock **exits with an error** and your session will not be locked.
>
> You can use the example config for a quick start, which can be found [here](https://github.com/hyprwm/hyprlock/blob/main/assets/example.conf).
## Command-line Arguments
See also: `hyprlock --help`.
| Argument | Description |
| --- | --- |
| `-v`/`--verbose` | Enable verbose logging |
| `-q`/`--quiet` | Disable logging |
| `-c`/`--config` FILE | Specify config file to use |
| `--display` NAME | Specify the Wayland display to connect to |
| `--grace` SECONDS | Set grace period in seconds before requiring authentication |
| `--immediate-render` | Do not wait for resources before drawing the background (Same as `general:immediate_render`) |
| `--no-fade-in` | Disable the fade-in animation when the lock screen appears |
| `-V`/`--version` | Show version information and exit |
| `-h`/`--help` | Show help and exit |
## Configuration
Configuration is done via a config file named `hyprlock.conf`.
Hyprlock searches for it in the following locations, in order:
1. `$XDG_CONFIG_HOME/hypr/hyprlock.conf`
1. `$HOME/.config/hypr/hyprlock.conf`
1. Each directory in `$XDG_CONFIG_DIRS` (e.g., `<dir>/hypr/hyprlock.conf`)
1. `/etc/xdg/hypr/hyprlock.conf`
The first match is used.
You can also specify an explicit path with `hyprlock --config <path>`.
### Variable Types
Hyprlock uses the following types in addition to Hyprland's [data types](../../../configuring/naming-conventions#data-types).
| Type | Description |
| --- | --- |
| layoutxy | vec2 with an optional `%` suffix, allowing users to specify sizes as percentages of the output size. Floats (e.g., 10.5) are supported, but only have an effect when used with `%`. Raw pixel values will just get rounded |
### General
Variables in the `general` category:
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `compositor_fade` | Uses compositor-controlled opacity to smoothly fade lock surface content together with compositor blur | bool | `false` |
| `disable_screencopy` | Disables taking a screencopy for applying background effects. Useful with a semitransparent background and Hyprland's `misc:session_lock_xray` enabled | bool | `false` |
| `fail_timeout` | Milliseconds until the ui resets after a failed auth attempt | int | `2000` |
| `fractional_scaling` | Whether to use fractional scaling. `0` - disabled, `1` - enabled, `2` - auto | int | `2` |
| `hide_cursor` | Hides the cursor instead of making it visible | bool | `false` |
| `ignore_empty_input` | Skips validation when no password is provided | bool | `false` |
| `immediate_render` | Makes hyprlock immediately start to draw widgets. Backgrounds will render `background:color` until their `background:path` resource is available | bool | `false` |
| `screencopy_mode` | Selects screencopy mode: `0` - GPU-accelerated, `1` - CPU-based (slow) | int | `0` |
| `text_trim` | Sets if the text should be trimmed, useful to avoid trailing newlines in commands' output | bool | `true` |
#### Compositor Fade and Live Background
Enable `general:compositor_fade` to fade lock surface content and compositor blur together using the existing [`fadeIn` and `fadeOut` animations](#animations).
This animates the contribution of compositor blur, **not the blur radius itself**.
If the compositor does not advertise the `hyprland_surface_manager_v1` Wayland protocol, hyprlock automatically falls back to the standard client-side fade.
For a live, blurred desktop backdrop, enable `misc:session_lock_xray` and `misc:session_lock_blur` in Hyprland's `hyprland.lua`:
```lua
hl.config({
misc = {
session_lock_xray = true,
session_lock_blur = true,
},
})
```
Use a transparent [background](#background) with an empty `path` in `hyprlock.conf`:
```ini
general {
compositor_fade = true
}
background {
monitor =
path =
color = rgba(0, 0, 0, 0.0)
}
animations {
enabled = true
bezier = linear, 1, 1, 0, 0
animation = fadeIn, 1, 5, linear
animation = fadeOut, 1, 5, linear
}
```
With this setup, the desktop behind the lock screen stays live.
An explicit `background:path = screenshot` still captures a static image at launch instead of showing a live backdrop, even with `compositor_fade` enabled.
### Authentication
Variables in the `auth` category:
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `pam:enabled` | Whether to enable PAM authentication | bool | `true` |
| `pam:module` | Sets the PAM module used for authentication. If the module isn't found in `/etc/pam.d`, "su" will be used as a fallback | string | `hyprlock` |
| `fingerprint:enabled` | Enables parallel fingerprint auth with fprintd | bool | `false` |
| `fingerprint:ready_message` | Sets the message that will be displayed when fprintd is ready to scan a fingerprint | string | `(Scan fingerprint to unlock)` |
| `fingerprint:present_message` | Sets the message that will be displayed when a finger is placed on the scanner | string | `Scanning fingerprint` |
| `fingerprint:retry_delay` | Sets the delay in ms after an unrecognized finger is scanned before another finger can be scanned | int | `250` |
> [!NOTE]
> At least one enabled authentication method is required.
### Animations
Variables in the `animations` category:
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| enabled | Whether to enable animations | bool | `true` |
#### Keywords
The `animation` and `bezier` keywords can be used:
For example:
```ini
bezier = linear, 1, 1, 0, 0
animation = fade, 1, 1.8, linear
```
Available animations can be found in the [animation tree](#animation-tree).
The optional `STYLE` parameter for the `animation` keyword is currently unused by hyprlock.
Check out Hyprland's [animation documentation](../../../configuring/core/animations) for more information.
#### Animation Tree
```plain
global
↳ fade
↳ fadeIn - fade to lock screen
↳ fadeOut - fade back to the Wayland session
↳ inputField
↳ inputFieldColors - fade between colors and gradients
↳ inputFieldFade - fade_on_empty animation
↳ inputFieldWidth - adaptive width animation
↳ inputFieldDots - fade in/out for individual dots in the input field
```
### System Configuration
On Arch Linux, by default, hyprlock integrates with [pambase](https://archlinux.org/packages/?name=pambase) through `pam_faillock.so`, which forces a 10 minute timeout after 3 failed unlocks.
If you would like to change this, refer to the [Arch Linux wiki](https://wiki.archlinux.org/title/Security#Lock_out_user_after_three_failed_login_attempts) and update the `/etc/security/faillock.conf` file with parameters `unlock_time`, `fail_interval`, and `deny` as needed.
## Keyboard Shortcuts and Actions
The following keys and key-combinations describe hyprlock's default behavior:
| Input | Description |
| --- | --- |
| `ESC` | Clear password buffer |
| `Ctrl + u` | Clear password buffer |
| `Ctrl + Backspace` | Clear password buffer |
The [`locked` flag](../../../configuring/core/binds/flags#bind-flags) can be used to allow specific Hyprland keybinds to also work while hyprlock is active (e.g., brightness/volume/media control).
## Widgets
The entire configuration of how hyprlock looks is done via widgets.
```ini
widget_name {
monitor =
# further options
}
```
### Monitor Selection
`monitor` is available for all widgets and can be left empty for "all monitors".
It takes the same string that is used to reference monitors in the Hyprland configuration.
So either use the portname (e.g., `eDP-1`) or the monitor description (e.g., `desc:Chimei Innolux Corporation 0x150C`).
See [Monitors](../../../configuring/core/monitors).
### Variable Substitution
The following variables in widget text options will be substituted.
- `$USER` - username (e.g., `linux-user`)
- `$DESC` - user description (e.g., `Linux User`)
- `$TIME` - current time in 24-hour format (e.g., `13:37`)
- `$TIME12` - current time in 12-hour format (e.g., `1:37 PM`)
- `$LAYOUT` - current keyboard layout
- `$ATTEMPTS` - failed authentication attempts
- `$FAIL` - last authentication fail reason
- `$PAMPROMPT` - PAM auth last prompt
- `$PAMFAIL` - PAM auth last fail reason
- `$FPRINTPROMPT` - fingerprint auth last prompt
- `$FPRINTFAIL` - fingerprint auth last fail reason
## Widget List
### General Remarks
- All rendered text supports
[pango markup](https://docs.gtk.org/Pango/pango_markup.html).
- Additionally hyprlock will parse `<br>` for your convenience.
(That's a linebreak.)
Remember to enable linebreaks in your spans with `allow_breaks="true"`.
- Positioning is done via halign, valign, position, and zindex.
Position is an added offset to the result of alignment.
- halign: `left`, `center`, `right`, `none`.
- valign: `top`, `center`, `bottom`, `none`.
- zindex: Widgets with larger numbers will be placed above widgets with smaller numbers.
All widgets default to 0, except background which defaults to -1.
- All `position` and `size` options can be specified in pixels or as percentages of the output size.
- pixels: `10, 10` or `10px, 10px`
- percentages: `10%, 10.5%`
- mixed: `10%, 5px`
- Supported image formats are png, jpg and webp (no animations though)
### Shadowable
Some widgets are shadowable, meaning they can have a shadow.
For those widgets, you get:
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `shadow_passes` | Passes for shadow, 0 to disable | int | `0` |
| `shadow_size` | Size for shadow | int | `3` |
| `shadow_color` | Shadow color | color | `rgb(0,0,0)` |
| `shadow_boost` | Boost shadow's opacity | float | `1.2` |
### Clickable
Some widgets are clickable.
Namely `label`, `image` and `shape`.
You can launch arbitrary commands when clicking on them by configuring the following option within the widget:
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `onclick` | Command to run when clicked | string | [[Empty]] |
### Background
Draws a background image or fills with color.
If `path` is empty or missing, it will use `color`; otherwise, the image will be used.
If `path` is `screenshot`, a screenshot of your desktop at launch will be used.
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `monitor` | Monitor to draw on | string | [[Empty]] |
| `path` | Image path, `screenshot` or empty to fill with `color` | string | [[Empty]] |
| `color` | Fallback background color | color | `rgba(17, 17, 17, 1.0)` |
| `blur_passes` | The amount of passes to perform. `0` disables blurring | int | `0` |
| `blur_size` | Blur size (distance) | int | `7` |
| `noise` | How much noise to apply | float | `0.0117` |
| `contrast` | Contrast modulation for blur | float | `0.8916` |
| `brightness` | Brightness modulation for blur | float | `0.8172` |
| `vibrancy` | Increase saturation of blurred colors | float | `0.1696` |
| `vibrancy_darkness` | How strong the effect of vibrancy is on dark areas | float | `0.05` |
| `reload_time` | Seconds between reloading, `0` to reload with `SIGUSR2`. Ignored if `path` is `screenshot` | int | `-1` |
| `reload_cmd` | Command to get new path. If empty, old path will be used | string | [[Empty]] |
| `crossfade_time` | Cross-fade time in seconds between old and new background on reload. A negative value means no cross-fade | float | `-1.0` |
| `zindex` | z-index of the widget | int | `-1` |
> [!NOTE]
> Blur options are taken from Hyprland.
> See [blur](../../../configuring/core/config-options#blur).
{{% details title="Example background" closed="true" %}}
```ini
background {
monitor =
path = screenshot
color = rgba(25, 20, 20, 1.0)
blur_passes = 2
}
```
{{% /details %}}
### Image
✓ Shadowable
✓ Clickable
Draws an image.
If `path` is empty or missing, nothing will be shown.
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `monitor` | Monitor to draw on | string | [[Empty]] |
| `path` | Image path | string | [[Empty]] |
| `size` | Size scale based on the lesser side of the image | int | `150` |
| `rounding` | Negative values result in a circle | int | `-1` |
| `border_size` | Border size | int | `4` |
| `border_color` | Border color | gradient | `rgba(221, 221, 221, 1.0)` |
| `rotate` | Rotation in degrees, counter-clockwise | int | `0` |
| `reload_time` | Seconds between reloading, `0` to reload with `SIGUSR2` | int | `-1` |
| `reload_cmd` | Command to get new path. if empty, old path will be used. don't run "follow" commands like `tail -F` | string | [[Empty]] |
| `position` | Position of the image | layoutxy | `0, 0` |
| `halign` | Horizontal alignment | string | `center` |
| `valign` | Vertical alignment | string | `center` |
| `zindex` | z-index of the widget | int | `0` |
{{% details title="Example image" closed="true" %}}
```ini
image {
monitor =
path = /home/me/cutie.png
size = 150
rounding = 0 # no rounding
position = 0, 200
halign = center
valign = center
}
```
{{% /details %}}
### Shape
✓ Shadowable
✓ Clickable
Draws a shape.
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `monitor` | Monitor to draw on | string | [[Empty]] |
| `size` | Size of the shape | layoutxy | 100, 100 |
| `color` | Color of the shape | color | `rgba(17, 17, 17, 1.0)` |
| `rounding` | Negative values result in a circle | int | `-1` |
| `rotate` | Rotation in degrees, counter-clockwise | int | `0` |
| `border_size` | Border size | int | `0` |
| `border_color` | Border color | gradient | `rgba(0, 207, 230, 1.0)` |
| `xray` | If `true`, make a "hole" in the background (rectangle of specified size, no rotation) | bool | `false` |
| `position` | Position of the shape | layoutxy | `0, 0` |
| `halign` | Horizontal alignment | string | `center` |
| `valign` | Vertical alignment | string | `center` |
| `zindex` | z-index of the widget | int | `0` |
{{% details title="Example shape" closed="true" %}}
```ini
shape {
monitor =
size = 360, 60
color = rgba(0, 0, 0, 0.0) # no fill
rounding = -1 # circle
border_size = 4
border_color = rgba(0, 207, 230, 1.0)
position = 0, 80
halign = center
valign = center
}
```
{{% /details %}}
### Input Field
✓ Shadowable
Draws a password input field.
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `monitor` | Monitor to draw on | string | [[Empty]] |
| `size` | Size of the input field | layoutxy | `400, 90` |
| `outline_thickness` | Thickness of the outline | int | `4` |
| `dots_size` | Size of the dots. [0.001 - 0.8] | float | `0.25` |
| `dots_spacing` | Spacing between dots. [-1.0 - 1.0] | float | `0.15` |
| `dots_center` | Whether to center the dots. Align left otherwise | bool | `true` |
| `dots_rounding` | Rounding of the dots | int | `-1` |
| `dots_text_format` | Text character(s) used for the input indicator, rounded rectangles are the default | string | [[Empty]] |
| `outer_color` | Border color | gradient | `rgba(17, 17, 17, 1.0)` |
| `inner_color` | Color of the inner box | color | `rgba(200, 200, 200, 1.0)` |
| `font_color` | Color of the font | color | `rgba(10, 10, 10, 1.0)` |
| `font_family` | Font family | string | `Noto Sans` |
| `fade_on_empty` | Fade the input field when empty | bool | `true` |
| `fade_timeout` | Milliseconds before `fade_on_empty` is triggered | int | `2000` |
| `placeholder_text` | Text rendered in the input box when it's empty | string | `<i>Input Password...</i>` |
| `hide_input` | Render an input indicator similar to swaylock instead of dots when set to `true` | bool | `false` |
| `hide_input_base_color` | This color's hue is randomly rotated (oklab color space) to get colors for `hide_input` | color | `rgba(153, 170, 187)` |
| `rounding` | `-1` means complete rounding (circle/oval) | int | `-1` |
| `check_color` | Color accent when waiting for the authentication result | gradient | `rgba(204, 136, 34, 1.0)` |
| `check_text` | Text rendered when waiting for the authentication result | string | [[Empty]] |
| `fail_color` | Color accent when authentication fails | gradient | `rgba(204, 34, 34, 1.0)` |
| `fail_text` | Text rendered when authentication fails | string | `<i>$FAIL <b>($ATTEMPTS)</b></i>` |
| `capslock_color` | Color accent when Caps Lock is active | gradient | [[Empty]] |
| `numlock_color` | Color accent when numlock is active | gradient | [[Empty]] |
| `bothlock_color` | Color accent when both locks are active | gradient | [[Empty]] |
| `invert_numlock` | Change color if numlock is off | bool | `false` |
| `swap_font_color` | Swap font and inner colors on color change events | bool | `false` |
| `position` | Position of the input field | layoutxy | `0, 0` |
| `halign` | Horizontal alignment | string | `center` |
| `valign` | Vertical alignment | string | `center` |
| `zindex` | z-index of the widget | int | `0` |
> [!NOTE] **Colors information**
> When `outline_thickness` is set to `0`, the color of the inner box will be changed instead of the outer.
>
> Behavior of `swap_font_color` is as follows:
> - `outline_thickness` is `0`: if set, font color will be swapped with inner one on color change events (e.g., Caps Lock on or password check).
> - `outline_thickness` is not `0`: if set, font and inner colors will be swapped on password check and authentication failure.
> - `swap_font_color` will narrow the accent colors from a gradient to a single color by using the first specified color.
`placeholder_text` and `fail_text` both support [variable substitution](#variable-substitution).
{{% details title="Example input-field" closed="true" %}}
```ini
input-field {
monitor =
size = 20%, 5%
outline_thickness = 3
inner_color = rgba(0, 0, 0, 0.0) # no fill
outer_color = rgba(33ccffee) rgba(00ff99ee) 45deg
check_color = rgba(00ff99ee) rgba(ff6633ee) 120deg
fail_color = rgba(ff6633ee) rgba(ff0066ee) 40deg
font_color = rgb(143, 143, 143)
fade_on_empty = false
rounding = 15
position = 0, -20
halign = center
valign = center
}
```
{{% /details %}}
### Label
✓ Shadowable
✓ Clickable
Draws a label.
| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `monitor` | Monitor to draw on | string | [[Empty]] |
| `text` | Text to render | string | `Sample Text` |
| `text_align` | Multi-line text alignment inside label container. center/right or any value for default left | string | `center` |
| `color` | Color of the text | color | `rgba(254, 254, 254, 1.0)` |
| `font_size` | Size of the font | int |`16` |
| `font_family` | Font family | string | `Sans` |
| `rotate` | Rotation in degrees, counter-clockwise | int | `0` |
| `position` | Position of the label | layoutxy | `0, 0` |
| `halign` | Horizontal alignment | string | `center` |
| `valign` | Vertical alignment | string | `center` |
#### Dynamic Labels
The `text` option supports [variable substitution](#variable-substitution) and launching shell commands.
For example:
```ini
text = cmd[update:1000] echo "<span foreground='##ff2222'>$(date)</span>"
```
> [!NOTE]
> - `update:` time is in milliseconds.
> - label can be forcefully updated by specifying `update:<time>:1` or `update:<time>:true` and sending `SIGUSR2` to hyprlock, `<time>` can be `0` in this case.
> - `$ATTEMPTS[<string>]` format can be used to show `<string>` when there are no failed attempts.
> You can use pango-markup here. `<string>` can be empty to hide.
> - `$LAYOUT[<string0>,<string1>,...]` format is available to replace indexed layouts.
> You can use settings from `hyprland.lua` (e.g., `$LAYOUT[en,ru,de]`).
> Also, a single `!` character will hide layout (e.g., `$LAYOUT[!]` will hide default (0 indexed) and show others).
> - `$TIME` and `$TIME12` will use timezone from the TZ environment variable.
> If it's not set, the system timezone will be used, falling back to UTC in case of errors.
> - Variables seen above are parsed _before_ the command is run.
> - **Do not** run commands that never exit.
> This will hang the `AsyncResourceGatherer` and you won't have a good time.
{{% details title="Example label" closed="true" %}}
```ini
label {
monitor =
text = Hi there, $USER
color = rgba(200, 200, 200, 1.0)
font_size = 25
font_family = Noto Sans
position = 0, 80
halign = center
valign = center
}
```
{{% /details %}}
## User Signals
- `SIGUSR1`: Unlocks hyprlock.
For example, you can switch to another TTY and run `pkill -USR1 hyprlock`.
- `SIGUSR2`: Updates labels and images.
See above.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |