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/start.md
View on GitHub<!-- source: https://wiki.hypr.land/configuring/core -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
# Configuring Hyprland: Basics
---
weight: 40
title: Configuring
---
> [!IMPORTANT]
> ***This wiki is versioned!***
> By default, you are reading the wiki for _the latest Hyprland git commit_.
> Click on the version selector and select your version if you are running a tagged release (which you very likely are, you can check with `hyprctl version`).
## Section info
This section is all about configuring (or "ricing") your Hyprland experience.
It links to other pages where necessary, and will walk you through:
- The configuration file
- Every option and function in it
- Extending functionality via scripts
- And more!
It also contains some sample configurations you can take inspiration from.
Start in the [Core page](./core).
---
---
weight: 30
title: Core
---
> [!WARNING]
> The default config is not complete and does not include every Hyprland option or feature.
> For every configuration option, see the pages linked from this wiki section.
The config is located in `$XDG_CONFIG_HOME/hypr/hyprland.lua`.
In most cases, that maps to `~/.config/hypr/hyprland.lua`.
You can pass arguments while starting Hyprland (`start-hyprland`), but you must pass your arguments after `--`.
For instance, to use `--config` (or `-c`) to make Hyprland load a non-default config, you might use `start-hyprland -- --config ~/myRices/medium_rare/hyprland.lua`.
If no configuration exists, Hyprland will create an [example config](https://github.com/hyprwm/Hyprland/blob/main/example/hyprland.lua).
Remove `hl.config({ autogenerated = true })` to remove the autogenerated warning banner.
Configuration is reloaded when changes to files are detected.
To reload manually, use `hyprctl reload`.
To get information (class, size, tags, etc.), use:
- `hyprctl clients` to show all windows
- `hyprctl activewindow` to show only the active window
## Language style and syntax
Hyprland uses [Lua](https://lua.org/) for its configuration file.
It's an easy-to-use and performant scripting language used in various pieces of software.
### General Hyprland Lua tips
#### Example config
The example config file can be found [here](https://github.com/hyprwm/Hyprland/blob/main/example/hyprland.lua).
#### Using Multiple Configuration Files
Configuration can be split across several files or modules.
To load other modules, use Lua's [`require`](#require) function.
Modules may be specified as an absolute path, a path relative to the location of `hyprland.lua`, or a module name installed at the system level.
In `require`, `.` or `/` can be used as a directory separator, though `.` should be preferred for relative imports.
The `*` wildcard can be used to load multiple files from a directory or to search in all directories at the given path.
When a wildcard is used, the path must be in UNIX format.
{{% details title="Examples" closed="true" %}}
```lua
-- refers to $XDG_CONFIG_HOME/hypr/awesomeconf/animation.lua
require("awesomeconf.animation")
-- refers to $XDG_CONFIG_HOME/hypr/awesomeconf/keybinds.lua
require("awesomeconf/keybinds")
-- will try to load all files in a directory
require("./lua/*")
-- will try to load "loadme.lua" files from all subdirectories
require("./lua/*/loadme")
-- will load "us.lua" from /usr/share/among
require("/usr/share/among/us")
```
{{% /details %}}
#### Require
Use `require` to load other files into your config.
This is **highly** recommended because each `require` call is specifically made by Hyprland to be a separate Lua "scope", so errors in one `require`d file do _not_ stop execution of other files.
It's important to note that many errors will kill the execution of a given lua file.
Error behavior is described further [below](#error-behavior).
`require`'s protective behavior does not apply to module loading.
If you attempt to load a module that does not exist, `require` will throw an actual error, in the file from which it was invoked.
That is, doing `require("nonexistent")` in your main Hyprland config _will kill the execution of your main config_.
If you want to prevent such errors from breaking stuff, or even detect and respond to them at runtime, use Lua's `pcall()` function, for example:
```lua
local status, value = pcall(require, "maybe-nonexistent")
if status then
print("Successfully loaded module, it returned:", value)
else
print("Failed to load module, its error message was:", value)
end
```
##### Ignoring `require`'s protection
To ignore scope separation, the original Lua `require` is available as `__require`.
It can be used directly, or restored as the default by setting `require = __require`.
This latter option may be helpful if you load third-party modules that are broken by Hyprland's error-protection behavior.
#### Editor autocompletion
A pre-generated Lua stub can be found in the `/usr/share/hypr/stubs/` directory (NixOS systems can find it in `/run/current-system/sw/share/hypr/stubs/`).
Configure your LSP to include that directory in your Lua workspace to enable autocompletion.
If you would prefer not to set up an LSP, the stubs are also human-readable.
{{< tabs >}}
{{< tab name="Generic" >}}
Add a `.luarc.json` file in your repository root, then:
```json
{
"workspace": {
"library": [
"/usr/share/hypr/stubs"
]
}
}
```
{{< /tab >}}
{{< tab name="VS Code" >}}
Create a `settings.json` file in `.vscode/` (if it doesn't exist, make it), then:
```json
{
"Lua.workspace.library": [
"/usr/share/hypr/stubs"
]
}
```
{{< /tab >}}
{{< /tabs >}}
#### Error behavior
Hyprland attempts, as much as it can, to make errors as non-destructive as possible.
However, some errors cannot be handled cleanly:
- Fundamental Lua syntax errors will make Hyprland refuse to reload your config and pop an error.
- Runtime Lua syntax errors will abort execution of the current Lua file and pop an error (e.g., calling a `nil`).
- Runtime Hyprland type errors will continue execution and pop an error (e.g., passing a string instead of a float to `hl.*`).
- Runtime errors during async execution (e.g., a keybind function) will pop a notification about the error.
If an errors occurs before any of the binds were registered, Hyprland will register a few emergency keybinds: `SUPER + Q` to open terminal, `SUPER + R` to open hyprlauncher, and `SUPER + M` to exit Hypland.
This will be mentioned in the error popup.
#### Infinite loops, reentrant events
Hyprland has protections in place to avoid scripts that would run forever from taking down the session.
These will kill your script after a given timeout/limit has been reached.
#### Standard library
The Lua standard libraries are loaded by default.
Lua scripts can **execute arbitrary code on your machine**; make sure you trust your config source.
#### Testing with REPL
The API and Lua state can be easily explored with the built in [Lua REPL in hyprctl](./advanced-configuration/using-hyprctl/#repl).
---
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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |