hyprland-schema

Typed Python schema for every Hyprland configuration option — with defaults, ranges, and descriptions. Generated from Hyprland's option-metadata source (ConfigDescriptions.hpp on v0.54.x and older, ConfigValues.cpp on v0.55.0 and newer, hyprwm/Hyprland#13817). Zero runtime dependencies — stdlib only.

Installation

pip install hyprland-schema

Usage

import hyprland_schema

# Schema version
print(hyprland_schema.HYPRLAND_VERSION)  # "v0.56.1"

# Lookup by key
border = hyprland_schema.OPTIONS_BY_KEY["general:border_size"]
print(border.type, border.default, border.min, border.max)
# int 1 0 20

# Filter by section
for opt in hyprland_schema.get_section("general"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Filter by subsection
for opt in hyprland_schema.get_subsection("decoration", "blur"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Iterate all options
for opt in hyprland_schema.OPTIONS:
    print(f"{opt.key}: {opt.type}")

# Export as JSON
json_str = hyprland_schema.get_json()

Loading older Hyprland versions

import hyprland_schema

# List all bundled versions (newest first)
print(hyprland_schema.available_versions())

# Load schema for a specific version
schema = hyprland_schema.load("v0.54.2")
print(schema.version, len(schema.options))

# Schema objects have the same filtering API
for opt in schema.get_section("general"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Lookup on a Schema
border = schema.options_by_key["general:border_size"]

The version is accepted with or without the v prefix, so the bare number hyprctl reports can be passed straight through; schema.version reports the tag spelling either way.

Resolution order for load():

1. Latest bundled version — instant (pre-parsed).
2. Older bundled version — reconstructed via reverse migrations.
3. Disk cache at ~/.cache/hyprland-schema/ — no network needed.
4. GitHub fetch — downloads ConfigValues.cpp (or, for older tags, ConfigDescriptions.hpp) and parses it.

API

Schema

Schema is a frozen dataclass returned by load(). It holds options for a specific Hyprland version.

HyprOption fields

Requirements

• Python >= 3.12

License

MIT