You may install more plugins by using 3rd party or custom Python packages. Pyprland provides the following plugins out of the box:
- scratchpads implements dropdowns & togglable poppups
- monitors allows relative placement of monitors depending on the model
- expose easily switch between scratchpads and active workspace :
- workspaces_follow_focus provides commands and handlers allowing a more flexible workspaces usage on multi-monitor setups. If you think the multi-screen behavior of hyprland is not usable or broken/unexpected, this is probably for you.
- lost_windows brings lost floating windows (which are out of reach) to the current workspace
- toggle_dpms toggles the DPMS status of every plugged monitor
- magnify toggles zooming of viewport or sets a specific scaling factor
- shift_monitors adds a self-configured "swapactiveworkspaces" command
expose
This plugin have two features:
The two commands are not really related, one allows the "expose" effect, showing every client window on the focused screen. The other one allows you to have some kind of dynamic scratchpad, which can be used to minimize (and back) the windows. They have in common the way they display the client windows to "restore" or "focus" to a specific one.
Commands
-
toggle_minimized [name]: moves the focused window to the special workspace "name", or move it back to the active workspace. If none set, a special workspace called "minimized" will be used. To toggle the state back to a normal workspace, you'll need tohyprctl dispatch togglespecialworkspace minimized(if you didn't set a name, since "minimized" is the default special workspace that will be used). It can also be achieved with a keybinding:bind = $mainMod SHIFT, N, togglespecialworkspace, minimizedinhyprland.conf -
expose: expose every client on the active workspace. If expose is already active, then restores everything and move to the focused window.
Example usage in hyprland.conf:
bind = $mainMod, N, exec, pypr toggle_minimized
Configuration
include_special (optional)
defaults to false
Also include windows in the special workspaces during the expose.
shift_monitors
Swaps the workspaces of every screen in the given direction. Note the behavior can be hard to predict if you have more than 2 monitors, suggestions are welcome.
Command
shift_monitors <direction>: swaps every monitor's workspace in the given direction
Example usage in hyprland.conf:
bind = $mainMod SHIFT, O, exec, pypr shift_monitors +1
magnify
Command
zoom [value]: if no value, toggles magnification. If an integer is provided, it will set as scaling factor.
Configuration
factor (optional)
defaults to 2
Scaling factor to be used when no value is provided.
toggle_dpms
Command
toggle_dpms: if any screen is powered on, turn them all off, else turn them all on
lost_windows
Command
attract_lost: brings the lost windows to the current screen / workspace
monitors
Syntax:
"monitors": {
"placement": {
"<partial model description>": {
"placement type": "<monitor name/output>"
},
"unknown": "<command to run for unknown monitors>"
}
}
Example:
"monitors": {
"unknown": "notify-send 'Unknown monitor'",
"placement": {
"Sony": {
"topOf": "HDMI-1"
}
}
}
Requires wlr-randr.
Allows relative placement of monitors depending on the model ("description" returned by hyprctl monitors).
Configuration
placement
Supported placements are:
- leftOf
- topOf
- rightOf
- bottomOf
unknown (optional)
If set, runs the associated command for screens which aren't matching any of the provided placements (pattern isn't found in monitor description).
Note this is supposed to be a short lived command which will block the rest of the process until closed. In other words no plugin will be processed while this command remains open.
workspaces_follow_focus
Make non-visible workspaces follow the focused monitor. Also provides commands to switch between workspaces wile preserving the current monitor assignments:
Syntax:
"workspaces_follow_focus": {
"max_workspaces": <number of workspaces>
}
Command
change_workspace<direction>: changes the workspace of the focused monitor
Example usage in hyprland.conf:
bind = $mainMod, K, exec, pypr change_workspace +1
bind = $mainMod, J, exec, pypr change_workspace -1
Configuration
max_workspaces
Limits the number of workspaces when switching, defaults to 10.
scratchpads
Defines commands that should run in dropdowns. Successor of hpr-scratcher, it's fully compatible, just put the configuration under "scratchpads".
Syntax:
"scratchpads": {
"scratchpad name": {
"command": "command to run"
}
}
As an example, defining two scratchpads:
- term which would be a kitty terminal on upper part of the screen
- volume which would be a pavucontrol window on the right part of the screen
Example:
"scratchpads": {
"term": {
"command": "kitty --class kitty-dropterm",
"animation": "fromTop",
"margin": 50,
"unfocus": "hide"
},
"volume": {
"command": "pavucontrol",
"animation": "fromRight"
}
}
In your hyprland.conf add something like this:
exec-once = pypr
# Repeat this for each scratchpad you need
bind = $mainMod,V,exec,pypr toggle volume
windowrule = float,^(pavucontrol)$
windowrule = workspace special silent,^(pavucontrol)$
bind = $mainMod,A,exec,pypr toggle term
$dropterm = ^(kitty-dropterm)$
windowrule = float,$dropterm
windowrule = workspace special silent,$dropterm
windowrule = size 75% 60%,$dropterm
And you'll be able to toggle pavucontrol with MOD + V.
Commands
toggle <scratchpad name>: toggle the given scratchpadshow <scratchpad name>: show the given scratchpadhide <scratchpad name>: hide the given scratchpad
Note: with no argument it runs the daemon (doesn't fork in the background)
Configuration
command
This is the command you wish to run in the scratchpad.
animation (optional)
Type of animation to use
null/""/ not defined (no animation)- "fromTop" (stays close to top screen border)
- "fromBottom" (stays close to bottom screen border)
- "fromLeft" (stays close to left screen border)
- "fromRight" (stays close to right screen border)
offset (optional)
number of pixels for the animation.
unfocus (optional)
when set to true, allow to hide the window when the focus is lost when set to "hide"
margin (optional)
number of pixels separating the scratchpad from the screen border
lazy (optional)
when set to true, prevents the command from being started when pypr starts, it will be started when the scratchpad is first used instead.
size (optional)
string in format "X% Y%", where X and Y is percentage of monitor's width and height accordingly. Every time scratchpad is shown, window will be resized depending on the monitor size, it displayed on.
For example on monitor of size 800x600 and "size": "80% 80%" in config scratchpad always have size 640x480, regardless of which monitor it was first launched on.
position (optional)
every time scratchpad is shown, window will be moved to specified position relative to top left corner. For format and example see size.
example of scratchpad that always occupy top half of the screen:
"scratchpads": {
"term_quake": {
"command": "wezterm start --class term_quake",
"position": "0% 0%",
"size": "100% 50%"
}
}
class (optional)
Match the client window using the provided WM_CLASS instead of the PID of the process.
Use it in case of troubles - check this wiki page