xdg-desktop-portal-wlr(5)

💅 xdg-desktop-portal-wlr(5)

okay so bestie, welcome to the File Formats Manual corner of the universe 🎀 this little page is all about xdg-desktop-portal-wlr, the manual page for the portal backend (page number 5, if you're keeping track, and yes she's iconic for it).

---

✨ NAME ✨

xdg-desktop-portal-wlr — literally an xdg-desktop-portal backend for wlroots, no cap 🫶

---

🌸 DESCRIPTION 🌸

xdg-desktop-portal-wlr (or xdpw for short, because we're besties and we use nicknames) lets applications request screenshots and screencasts through xdg-desktop-portal inside wlroots-based Wayland compositors. that's the whole vibe ✨

xdpw will try to load its config file from these locations, in order:

• $XDG_CONFIG_HOME/xdg-desktop-portal-wlr/$XDG_CURRENT_DESKTOP
• $XDG_CONFIG_HOME/xdg-desktop-portal-wlr/config
• /etc/xdg/xdg-desktop-portal-wlr/$XDG_CURRENT_DESKTOP
• /etc/xdg/xdg-desktop-portal-wlr/config

$XDG_CONFIG_HOME defaults to ~/.config (the classic 🏠). and $XDG_CURRENT_DESKTOP can be a colon separated list — every element of that list gets tried, one by one, like she's going down the group chat roster 💅

the config files use the INI file format. example time, look at her go:

[screencast]
output_name=HDMI-A-1
max_fps=30
exec_before=disable_notifications.sh
exec_after=enable_notifications.sh
chooser_type=simple
chooser_cmd=slurp -f 'Monitor: %o' -or

---

🦋 SCREENCAST OPTIONS 🦋

these options need to be placed under the [screencast] section, mkay? no straying 🎀

• output_name = name — picks which output gets screencast 💖 this one is used together with chooser_type = none. and if you wanna know the available outputs? grab 'em via wayland-info(1) (look under the wl_output section, iykyk).
• max_fps = limit — caps the frames per second at whatever rate you hand it 🌈 this is highkey useful for reducing CPU usage when capturing frames at the output's refresh rate just isn't necessary, bestie.
• exec_before = command — runs command before starting a screencast. the command gets executed within sh 🐚
• exec_after = command — runs command after ending all the screencasts. also executed within sh. see the symmetry? we love a matched set 💜
• chooser_cmd = command — run this command to select an output ✨ for more deets, see OUTPUT CHOOSER below 👇
• chooser_type = type — specifies the input sent to the chooser 🎯 the supported types are:
  • default: xdpw will try to use the first chooser found in the list of hardcoded choosers (slurp, wmenu, wofi, rofi, bemenu, mew, fuzzel) and will fallback to an arbitrary output if none of those were found. she's got backups for her backups 💀
  • none: xdpw will allow screencast either on the output given by output_name, or — if that's empty — an arbitrary output, with no further interaction at all. zero small talk 🙈
  • simple, dmenu: xdpw will launch the chooser given by chooser_cmd. for more deets, see OUTPUT CHOOSER.
• force_mod_linear = bool — forces buffers with implicit modifiers to be linear (experimental) 🔥 setting this option to 1 will force xdpw to allocate dma-bufs with implicit modifier as linear. this option shouldn't be required on single gpu setups, but it can increase compatibility, especially on setups with multiple gpus 👑

⚠️ heads up bestie: this option is experimental and can be removed or replaced in future versions. so don't build your whole personality around it 😭

🧚 OUTPUT CHOOSER

the chooser can be any program or script with the following behaviour, periodt:

• It returns any error code except 127. the error code 127 is internally used to signal that no command could be found, and all output from it will be ignored 💀
• It returns a string on stdout, which is valid if it matches one of the following:
  • For simple choosers:
    • The prefix "Monitor: " followed by the name of a valid output as given by wayland-info(1).
    • The prefix "Window: " followed by the ext-foreign-toplevel-list-v1 identifier as given by lswt(1).
  • For dmenu choosers: one of the lines provided via stdin.
  • Everything else will be handled as declined by the user 🙈
• To signal that the user has declined the screencast, the chooser should exit without anything on stdout. silent exit = no screenshot for you, respectfully 🫶

supported types of choosers via the chooser_type option:

• simple: the chooser is just called, without anything further on stdin. minimal, clean, main character energy ✨
• dmenu: the chooser receives a newline separated list (dmenu style) of outputs on stdin 🌈

---

👑 SEE ALSO 👑

pipewire(1) — go say hi 🫶

---

and that's the whole page bestie!! 💖 this was the File Formats Manual for xdg-desktop-portal-wlr(5), dated 2026-09-07, and it ate, fr fr 🎀✨💅