DOCSEARCHbyAlgolia
Submit Docs

Hyprland Wayland Compositor

repository·main·Indexed 12 days ago

https://github.com/hyprwm/hyprland

A highly customizable, dynamic tiling Wayland compositor focused on aesthetics and performance. Built independently without relying on wlroots, it features gradient borders, blur, animations, and a powerful plugin system. Includes hyprctl, a command-line utility for IPC-based control, dynamic configuration updates via keywords or Lua expressions, and comprehensive system state querying.

Tokens
9.9K
Snippets
35
Records
52
Agent score
97%

What's inside Hyprland

  1. Overview of Hyprland features

    main

    Hyprland is a 100% independent, dynamic tiling Wayland compositor. Unlike many other compositors, it does not rely on wlroots, libweston, kwin, or mutter.

    Key capabilities include:

    • Visuals: Gradient borders, blur, animations with custom bezier curves, and shadows.
    • Window Management: Tiling, pseudotiling, floating, fullscreen modes, window groups (tabbed mode), and special workspaces (scratchpads).
    • Extensibility: Powerful plugin support with a built-in plugin manager and socket-based IPC.
    • Performance: Tearing support for gaming and instant configuration reloading upon saving.
    • Layouts: Two built-in layouts with additional layouts available via plugins.
    • Rules: Powerful window, monitor, and layer rules.
    • Input: Native IME and Input Panels support, and global keybinds passed to specific applications.

  3. Obtain a debug Hyprland coredump

    main

    To provide a high-quality debug coredump that speeds up bug fixing, follow these steps. This requires using the latest git version.

    1. Sync your source: git pull --recurse-submodules.
    2. Compile Hyprland in debug mode (refer to Contributing and Debugging guide). Note that debug mode uses hyprlandd.lua instead of hyprland.lua.
    3. Launch Hyprland from a TTY with Address Sanitizer (ASAN) enabled:
      ASAN_OPTIONS="log_path=asan.log" ~/path/to/Hyprland
    4. Reproduce the crash. Hyprland will close immediately.
    5. Locate the file asan.log.XXXXX in your home directory (~), where XXXXX is the PID of the crashed instance.
    6. Attach this file to your issue.
    ASAN_OPTIONS="log_path=asan.log" ~/path/to/Hyprland

  5. Report a bug in Hyprland

    main

    When reporting a bug, ensure you have checked the FAQ and Configuring Page to avoid duplicates.

    For non-crashing bugs (invalid behavior):

    • Provide steps to reproduce.
    • State the expected outcome.
    • State the noted outcome.

    For crashing bugs: In addition to the steps above, you MUST provide:

    • The Hyprland log.
    • Your configuration file.
    • The Hyprland Crash Report (for v0.22.0beta and up) OR a Coredump (for v0.21.0beta and below).

    Important: Do not use a package-managed version to report bugs. Clone and compile Hyprland from source to ensure you are reporting on the latest code.

  6. Use hyprctl to control Hyprland

    main

    hyprctl is a command-line utility used to control various parts of the Hyprland compositor via CLI or scripts. It supports two main categories of commands: Control Commands (to change state or execute actions) and Info Commands (to query the current state).

    hyprctl [flags] [command] [args]

  7. Configure Window Rules in Hyprland

    main

    Hyprland uses window rules to define specific behaviors for windows based on various criteria. Rules can be categorized into static rules (properties that are set when the window is first created) and dynamic rules (properties that can be changed while the window is running).

    Static Properties

    Static rules are applied during window creation and include:

    • Placement: monitor, workspace, group, size, position, center.
    • State: floating, fullscreen, maximize, pseudo, pin, noInitialFocus.
    • Behavior: suppressEvent (list of events to ignore), noCloseFor.

    Dynamic Properties

    Dynamic rules can be applied to existing windows. Common dynamic properties include:

    • Visuals: alpha, alphaInactive, alphaFullscreen, rounding, borderSize, activeBorderColor, inactiveBorderColor, noBlur, noDim, noShadow, noAnim, opacity.
    • Input/Focus: allowsInput, focusOnActivate, noFocus, stayFocused, confinePointer, noFollowMouse.
    • Rendering: nearestNeighbor, renderUnfocused, xray, tearing, RGBX.
    • Constraints: minSize, maxSize, keepAspectRatio.
    • Other: idleInhibitMode (using eIdleInhibitMode), animationStyle, tonemap.

  9. Extend Hyprland configuration via Lua

    main

    Hyprland provides a CConfigManager that allows developers to extend the configuration system using Lua scripts. This interface enables registering plugin-specific Lua functions, providing custom layout providers, and managing configuration values through a Lua state.

    Key capabilities include:

    • Plugin Lua Functions: Registering functions within a specific namespace that can be called from Lua.
    • Layout Providers: Registering custom layout logic via registerLuaLayoutProvider.
    • Arbitrary Execution: Using eval() to execute Lua code strings within the current Hyprland Lua state.
    • Event Handling: Interacting with the configuration lifecycle through Lua-based event handlers.

  10. Use hyprctl to interact with Hyprland

    main

    hyprctl is the command-line interface for interacting with the Hyprland compositor via its IPC (Inter-Process Communication) socket. It allows you to dispatch commands, manage outputs, configure decorations, and more.

    Core Concepts

    • Instance Signature: hyprctl identifies which Hyprland instance to talk to using the HYPRLAND_INSTANCE_SIGNATURE environment variable. If this is not set, hyprctl cannot connect to the compositor.
    • Socket Communication: Commands are sent over a Unix domain socket located at $XDG_RUNTIME_DIR/<instance_signature>/.socket.sock.
    • Command Format: Commands are typically passed as arguments following the hyprctl binary. Internally, these are mapped to specific IPC endpoints (e.g., /dispatch, /keyword, /output).

    Common CLI Flags

    • -j or --json: Output the result in JSON format (where supported).
    • -r or --repl: Enter the interactive Lua REPL mode.
    • -f or --follow: Follow the log output (only supported by the rollinglog command).
    • -i or --instance: Specify a specific Hyprland instance by its signature or index.
    • -q or --quiet: Suppress output.
    • --batch: Execute multiple commands in a single request using the [[BATCH]] protocol.
    # Example: Dispatch a command
# hyprctl dispatch exec kitty

# Example: Get output information in JSON
# hyprctl output -j

# Example: Enter interactive REPL
# hyprctl repl

# Example: Follow logs
# hyprctl rollinglog --follow

  11. Use the hyprctl interactive REPL

    main

    The hyprctl tool includes an interactive Lua REPL mode. This allows you to execute commands continuously in a shell-like environment.

    To enter REPL mode, use the repl command:

    hyprctl repl

    In REPL mode:

    • Use > as the prompt for new lines.
    • Use >> as the prompt when a line is considered incomplete (e.g., due to a syntax error in a multi-line Lua command).
    • Commands entered in the REPL are added to the command history (via readline).
    • To exit, use standard terminal interrupt signals (like Ctrl+D or Ctrl+C).
    hyprctl repl

  12. Use the hyprpm CLI to manage Hyprland plugins

    main

    hyprpm is the Hyprland Plugin Manager. It is used to install, remove, enable, disable, and update plugins for the Hyprland compositor. Most operations that modify the system or plugin state may require elevated privileges, which hyprpm handles internally via cacheSudo.

    Commands

    CommandUsageDescription
    addhyprpm add <url> [git rev]Install a new plugin repository from a git URL. An optional git revision can be provided to bypass commit locks.
    removehyprpm remove <url|name|author/name>Remove an installed plugin repository.
    enablehyprpm enable <name|author/name>Enable a specific plugin.
    disablehyprpm disable <name|author/name>Disable a specific plugin.
    updatehyprpm updateCheck for and apply updates to all installed plugins and headers.
    reloadhyprpm reloadReload the hyprpm state and ensure all enabled plugins are loaded.
    listhyprpm listList all currently installed plugins.
    purge-cachehyprpm purge-cacheRemove the entire hyprpm cache, including built plugins, settings, and headers.

    Flags

    FlagShortDescription
    --help-hShow the help menu.
    --notify-nSend a Hyprland notification upon successful plugin load (errors/warnings always notify).
    --verbose-vEnable verbose logging.
    --force-fForce an operation, ignoring certain checks (e.g., update -f).
    --no-nixDisable nix develop for build commands, even if Hyprland is running in a Nix environment.
    --no-shallow-sDisable shallow cloning of Hyprland sources.
    --hl-urlPass a custom Hyprland source URL.

    Examples

    Install a plugin from a git repository:

    hyprpm add https://github.com/example/hyprland-plugin

    Install a specific revision of a plugin:

    hyprpm add https://github.com/example/hyprland-plugin v1.0.0

    Update all plugins and notify on success:

    hyprpm update --notify
    # Example usage
hyprpm add https://github.com/example/hyprland-plugin
hyprpm update
hyprpm list