Configuration

This page covers the configuration file format and available options.

File Location

The default configuration file is:

~/.config/pypr/config.toml

You can specify a different path using the --config flag:

pypr --config /path/to/config.toml

Format

Pyprland uses the TOML format. The basic structure is:

[pyprland]
plugins = ["plugin_name", "other_plugin"]

[plugin_name]
option = "value"

[plugin_name.nested_option]
suboption = 42

[pyprland] Section

The main section configures the Pyprland daemon itself.

Loading configuration...

include

List of additional configuration files to include. See Multiple Configuration Files for details.

notification_type

Controls how notifications are displayed:

Value	Behavior
"auto"	Adapts to environment (Niri uses notify-send, Hyprland uses hyprctl notify)
"notify-send"	Forces use of notify-send command
"native"	Forces use of compositor's native notification system

variables

Custom variables that can be used in plugin configurations. See Variables for usage details.

Examples

[pyprland]
plugins = [
    "scratchpads",
    "magnify",
    "expose",
]
notification_type = "notify-send"

Plugin Configuration

Each plugin can have its own configuration section. The format depends on the plugin:

# Simple options
[magnify]
factor = 2

# Nested options (e.g., scratchpads)
[scratchpads.term]
command = "kitty --class kitty-dropterm"
class = "kitty-dropterm"
size = "75% 60%"

See individual plugin documentation for available options.

Multiple Configuration Files

You can split your configuration across multiple files using include:

[pyprland]
include = [
    "~/.config/pypr/scratchpads.toml",
    "~/.config/pypr/monitors.toml",
]
plugins = ["scratchpads", "monitors"]

See Multiple Configuration Files for details.

Hyprland Integration

Most plugins provide commands that you'll want to bind to keys. Add bindings to your hyprland.lua:

--Define pypr command (adjust path as needed)
local pypr = "/usr/bin/pypr-client"

--example bindings
hl.bind(mainMod .. " + A", hl.dsp.exec_cmd(pypr .. " toggle term"))
hl.bind(mainMod .. " + B", hl.dsp.exec_cmd(pypr .. " expose"))
hl.bind(mainMod .. " + Z", hl.dsp.exec_cmd(pypr .. " zoom"))

TIP

For faster key bindings, use pypr-client instead of pypr. See Commands for details.

TIP

Command names can use dashes or underscores interchangeably. E.g., pypr shift_monitors and pypr shift-monitors are equivalent.

Validation

You can validate your configuration without running the daemon:

pypr validate

This checks your config against plugin schemas and reports any errors.

TIP

You can also use pypr-gui to browse available plugins, edit options with schema-aware forms, and validate interactively.

Tips

• See Examples for complete configuration samples
• See Optimizations for performance tips
• Only enable plugins you actually use in the plugins array