# Where to Find Hyprland's Configuration Parsing Logic: A Complete Guide to the Config System

> Discover Hyprland's configuration parsing logic within its Lua interpreter system. Explore key files like ConfigManager.cpp and CConfigManager.cpp for a comprehensive understanding.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: deep-dive
- Published: 2026-07-23

---

**Hyprland parses its configuration files through a Lua-based interpreter system implemented across [`src/config/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigManager.cpp), [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp), and [`src/config/ConfigValue.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigValue.cpp).**

Navigating the Hyprland codebase to understand how user settings are loaded requires tracing the **configuration parsing logic** through several architectural layers. Unlike traditional window managers that use static config files, Hyprland bootstraps a Lua interpreter to evaluate configuration directives as executable scripts. This article maps the precise file locations and function call chains within the `hyprwm/Hyprland` repository that handle config discovery, parsing, and value conversion.

## Entry Point and Config File Discovery

The **configuration parsing logic** begins in [`src/config/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigManager.cpp) with the `Config::initConfigManager()` function. This entry point determines which configuration file to load and instantiates the appropriate manager implementation.

When Hyprland starts, this function resolves the config file path through supplementary utilities, checks for file existence, and generates a default configuration if none is found. It then creates a unique pointer to the Lua-based config manager to handle the actual parsing.

```cpp
// src/config/ConfigManager.cpp – entry point
bool Config::initConfigManager() {
    const auto CFG_PATH = Supplementary::Jeremy::getMainConfigPath();
    std::filesystem::path filePath = CFG_PATH->path;

    // Create the Lua‑based config manager
    g_mgr = makeUnique<Lua::CConfigManager>();
    // …generate default config if needed…
}

```

## Lua-Based Parsing Implementation

The actual script evaluation occurs in [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp) within the `CConfigManager::init()` method. This class implements the **configuration parsing logic** by initializing a Lua state, registering Hyprland-specific functions, and executing the user's config file as a Lua script.

The `Lua::CConfigManager` creates a new interpreter instance with `luaL_newstate()`, opens standard libraries, and registers configuration directives such as `monitor`, `workspace`, and `bind` as Lua functions. It then calls `luaL_dofile()` to evaluate the script, capturing any runtime errors for logging.

```cpp
// src/config/lua/CConfigManager.cpp – parsing implementation
void CConfigManager::init() {
    // create a new Lua state
    lua_State* L = luaL_newstate();
    luaL_openlibs(L);

    // register Hyprland‑specific functions (e.g., monitor, workspace)
    registerHyprlandFunctions(L);

    // finally load the user’s config file
    if (luaL_dofile(L, configPath.c_str()) != LUA_OK) {
        const char* err = lua_tostring(L, -1);
        Log::logger->log(Log::CRIT, "[cfg] Lua error: {}", err);
    }
}

```

## Value Conversion and Internal Structures

Once Lua executes the configuration script, [`src/config/ConfigValue.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigValue.cpp) handles the conversion of parsed values into C++ structures. This module defines how Lua values map to internal Hyprland types such as `int`, `float`, `Vector2D`, and custom option objects.

The `Config::IConfigManager::getConfigValue()` method retrieves stored configuration values by name, returning type information and pointers that the rest of the compositor uses to query settings. This separation of concerns keeps the **configuration parsing logic** distinct from the value storage and retrieval mechanisms.

```cpp
// src/config/ConfigValue.cpp – converting Lua values
SConfigOptionReply Config::IConfigManager::getConfigValue(const std::string& name) {
    // Look up the stored value, return a pointer and type information
    // (used by the rest of the compositor to query config options)
}

```

## Step-by-Step Configuration Flow

Understanding the complete **configuration parsing logic** requires following the execution sequence across these three components:

1. **`Config::initConfigManager()`** in [`src/config/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigManager.cpp) — Discovers the config file path and instantiates the Lua manager.
2. **`Lua::CConfigManager::init()`** in [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp) — Sets up the Lua environment, registers config functions, and executes the script via `luaL_dofile`.
3. **Value handling** in [`src/config/ConfigValue.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigValue.cpp) — Converts Lua values into Hyprland's internal `Config::Values` hierarchy for runtime access.

## Summary

- **Configuration discovery** happens in [`src/config/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigManager.cpp), where `Config::initConfigManager()` determines the file path and creates the manager.
- **Script execution** is handled by `Lua::CConfigManager` in [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp), which runs the Lua interpreter and evaluates user configs.
- **Type conversion** is managed by [`src/config/ConfigValue.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigValue.cpp), mapping Lua values to C++ structures like `Vector2D` and `int`.
- The system uses `luaL_dofile()` to evaluate configuration files, with error handling that logs critical failures during startup.

## Frequently Asked Questions

### Where is the main configuration file path determined in Hyprland?

The path resolution occurs in [`src/config/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigManager.cpp) within the `Config::initConfigManager()` function. It calls `Supplementary::Jeremy::getMainConfigPath()` to determine the location, then checks if the file exists before initializing the Lua parser.

### How does Hyprland handle Lua errors during config parsing?

Errors are caught in [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp) immediately after calling `luaL_dofile()`. If the function returns anything other than `LUA_OK`, the error message is retrieved from the Lua stack using `lua_tostring()` and logged at the critical level, allowing the compositor to report specific syntax or runtime errors to the user.

### What types of values can be parsed from the Hyprland configuration?

According to the source code in [`src/config/ConfigValue.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigValue.cpp), the system supports converting Lua values to standard C++ types including `int`, `float`, and custom structures like `Vector2D`. The `getConfigValue()` method returns a `SConfigOptionReply` containing the type information and pointer to the stored value.

### Is the configuration parsing logic in Hyprland written entirely in Lua?

No, the **configuration parsing logic** is primarily implemented in C++. While the configuration files themselves are written in Lua and evaluated by the interpreter, the parser, value conversions, and function registrations are all native C++ code found in [`src/config/lua/CConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/CConfigManager.cpp) and related files.