Pyprland docs

Appearance

Getting Started ​

Pypr consists of two things:

  • A tool: pypr which runs the daemon (service) and allows you to interact with it
  • A config file: ~/.config/pypr/config.toml using the TOML format

IMPORTANT

  • With no arguments, pypr runs the daemon (doesn't fork to background)
  • With arguments, it sends commands to the running daemon

TIP

For keybindings, use pypr-client instead of pypr for faster response (~1ms vs ~50ms). See Commands: pypr-client for details.

TIP

Prefer a visual editor? Run pypr-gui to configure pyprland from your browser. See Commands: pypr-gui for details.

Installation ​

Check your OS package manager first:

  • Arch Linux: Available on AUR, e.g., with yay: yay pyprland
  • NixOS: See the Nix page for instructions

Otherwise, you may want using the uv way:

sh
# Install pyprland
uv tool install pyprland

else, install via pip (in a virtual environment):

sh
pip install pyprland

Minimal Configuration ​

Create ~/.config/pypr/config.toml with:

toml
[pyprland]
plugins = [
    "scratchpads",
    "gamemode",
    "magnify",
]

This enables only few plugins. See the Plugins page for the full list.

Running the Daemon ​

CAUTION

If you installed pypr outside your OS package manager (e.g., pip, virtual environment), use the full path to the pypr command. Get it with which pypr in a working terminal.

Option 1: Hyprland exec-once ​

Add to your hyprland.lua:

lua
hl.on("pyprland.start", function()
  hl.exec_cmd("/usr/bin/pypr")
end)

For debugging, use:

lua
hl.on("pyprland.start", function()
  hl.exec_cmd("/usr/bin/pypr --debug")
end)

Or to also save logs to a file:

lua
hl.on("pyprland.start", function()
  hl.exec_cmd("/usr/bin/pypr --debug $HOME/pypr.log")
end)

Option 2: Systemd User Service ​

Create ~/.config/systemd/user/pyprland.service:

ini
[Unit]
Description=Starts pyprland daemon
After=graphical-session.target
Wants=graphical-session.target
# Optional: wait for other services to start first
# Wants=hyprpaper.service
StartLimitIntervalSec=600
StartLimitBurst=5

[Service]
Type=simple
# Optional: only start on specific compositor
# For Hyprland:
# ExecStartPre=/bin/sh -c '[ "$XDG_CURRENT_DESKTOP" = "Hyprland" ] || exit 0'
# For Niri:
# ExecStartPre=/bin/sh -c '[ "$XDG_CURRENT_DESKTOP" = "niri" ] || exit 0'
ExecStart=pypr
Restart=always

[Install]
WantedBy=graphical-session.target

Then enable and start the service:

sh
systemctl enable --user --now pyprland.service

Verifying It Works ​

Once the daemon is running, check available commands:

sh
pypr help

If something isn't working, check the Troubleshooting page.

Next Steps ​