Core

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. 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 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.

Using Multiple Configuration Files

Configuration can be split across several files or modules. To load other modules, use Lua’s 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.

-- 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")

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 required 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.

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:

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.

{
  "workspace": {
    "library": [
      "/usr/share/hypr/stubs"
    ]
  }
}

{
  "Lua.workspace.library": [
    "/usr/share/hypr/stubs"
  ]
}

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.