Start

The config is located in $XDG_CONFIG_HOME/hypr/hyprland.lua. In most cases, that maps to ~/.config/hypr/hyprland.lua.

You can tell Hyprland to use a specific configuration file by using the --config (or -c) argument.

Hyprland will automatically generate an example config for you if you don’t have one. You can find an example config here.

By removing the line containing hl.config({ autogenerated = true }) you’ll remove the yellow warning.

The config is reloaded the moment you save it. However, you can use hyprctl reload to reload the config manually.

Language style and syntax

Hyprland uses Lua for its configuration file. It’s an easy and performant scripting language used throughout various pieces of software.

General Hyprland Lua tips

Autocompletions

We ship autogenerated Lua stubs in the repo’s meta/ directory. You can set up your LSP to automatically load them. This file is usually installed in /usr/share/hypr/stubs/.

{
  "workspace": {
    "library": [
      "/usr/share/hypr/stubs"
    ]
  },
  "diagnostics": {
    "globals": ["hl"]
  }
}

{
  "Lua.workspace.library": [
    "/usr/share/hypr/stubs"
  ],
  "Lua.diagnostics.globals": [
    "hl"
  ]
}

Require

Use require() to source 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

Hyprland attempts as much as we can to make errors as non-destructive as possible. However, it’s not always possible:

• 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 you are launching Hyprland, and you have a major error before your binds, in the same file, those binds will obviously not load.

To alleviate this, Hyprland will give you a few emergency keybinds (SUPER+Q, +R and +M for terminal, run, and exit respectively) and mention this 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.