Skip to content

marceloeatworld/hyprland-ai-skill

hyprland

Flagged

This skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.

FileKindSize
SKILL.mdskill md7.8 KB
references/.wiki-versionother50 B
references/animations.mdmarkdown6.1 KB
references/autostart.mdmarkdown770 B
references/binds.mdmarkdown24.0 KB
references/code-snippets.mdmarkdown16.5 KB
references/contributing.mdmarkdown19.4 KB
references/crashes-and-bugs.mdmarkdown5.9 KB
references/devices.mdmarkdown2.0 KB
references/dispatchers.mdmarkdown13.1 KB
references/environment-variables.mdmarkdown4.0 KB
references/faq.mdmarkdown13.8 KB
references/gestures.mdmarkdown8.4 KB
references/getting-started.mdmarkdown26.6 KB
references/hypr-libraries.mdmarkdown15.9 KB
references/hyprctl.mdmarkdown8.3 KB
references/hyprcursor.mdmarkdown2.2 KB
references/hypridle.mdmarkdown11.2 KB
references/hyprland-qt-support.mdmarkdown2.3 KB
references/hyprlauncher.mdmarkdown2.1 KB
references/hyprlock.mdmarkdown20.6 KB
references/hyprpaper.mdmarkdown3.4 KB
references/hyprpicker.mdmarkdown1.9 KB
references/hyprpolkitagent.mdmarkdown2.3 KB
references/hyprpwcenter.mdmarkdown436 B
references/hyprshutdown.mdmarkdown2.0 KB
references/hyprsunset.mdmarkdown4.8 KB
references/hyprsysteminfo.mdmarkdown457 B
references/ipc.mdmarkdown6.6 KB
references/layouts.mdmarkdown19.1 KB
references/lua-scripting.mdmarkdown9.6 KB
references/monitors.mdmarkdown14.1 KB
references/multi-gpu.mdmarkdown4.6 KB
references/naming-conventions.mdmarkdown4.7 KB
references/nix.mdmarkdown30.1 KB
references/notifications.mdmarkdown2.4 KB
references/nvidia.mdmarkdown1.3 KB
references/performance.mdmarkdown1.5 KB
references/permissions.mdmarkdown5.2 KB
references/plugins.mdmarkdown18.2 KB
references/start.mdmarkdown6.9 KB
references/systemd.mdmarkdown2.0 KB
references/tearing.mdmarkdown1.7 KB
references/useful-utilities.mdmarkdown47.4 KB
references/variables.mdmarkdown59.0 KB
references/virtual-gpu.mdmarkdown6.9 KB
references/window-rules.mdmarkdown19.2 KB
references/workspace-rules.mdmarkdown2.7 KB
references/xdph.mdmarkdown5.7 KB
references/xwayland.mdmarkdown2.0 KB
scripts/generate-references.shexecutablescript12.1 KB

references/xdph.md

View on GitHub
<!-- source: https://wiki.hypr.land/hypr-ecosystem/user/xdg-desktop-portal-hyprland -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->

---
weight: 60
title: xdg-desktop-portal-hyprland
---

An XDG Desktop Portal is a program that lets other applications communicate with the compositor through D-Bus.

A portal implements certain functionalities, such as opening file pickers or screen sharing.

[xdg-desktop-portal-hyprland](https://github.com/hyprwm/xdg-desktop-portal-hyprland) is Hyprland's xdg-desktop-portal implementation.
It allows for screen sharing, global shortcuts, etc.

> [!NOTE]
> Throughout this document, `xdg-desktop-portal-hyprland` will be referred to as XDPH.

> [!WARNING]
> XDPH doesn't implement a file picker.
> For that, it is recommended to install `xdg-desktop-portal-gtk` alongside XDPH.

## Installing

{{< tabs >}}

{{< tab name="Arch Linux" >}}

```sh
pacman -S xdg-desktop-portal-hyprland
```

or, for -git:

```sh
yay -S xdg-desktop-portal-hyprland-git
```

{{< /tab >}}

{{< tab name="NixOS" >}}

On NixOS, XDPH is already enabled by the [NixOS module for Hyprland](../../../nix/installing-hyprland-on-nixos), through `programs.hyprland.enable = true;`.

{{< /tab >}}

{{< tab name="Gentoo" >}}

### Unmask Dependencies

```plain {filename="/etc/portage/profile/package.unmask"}
dev-qt/qtbase
dev-qt/qtwayland
dev-qt/qtdeclarative
dev-qt/qtshadertools
```

### Apply Necessary useflags

```plain {filename="/etc/portage/package.use"}
dev-qt/qtbase opengl egl eglfs gles2-only
dev-qt/qtdeclarative opengl
sys-apps/xdg-desktop-portal screencast
```

### Unmask Dependencies and XDPH

```plain {filename="/etc/portage/package.accept_keywords"}
gui-libs/xdg-desktop-portal-hyprland
dev-qt/qtbase
dev-qt/qtwayland
dev-qt/qtdeclarative
dev-qt/qtshadertools
```

### Installation

```sh
eselect repository enable hyprovelay
emaint sync -r hyproverlay
emerge --ask --verbose gui-libs/xdg-desktop-portal-hyprland
```

{{< /tab >}}

{{< tab name="Manual" >}}

See [the GitHub repo's readme](https://github.com/hyprwm/xdg-desktop-portal-hyprland).

{{< /tab >}}

{{< /tabs >}}

## Usage

XDPH is automatically started by D-Bus, once Hyprland starts.

To check if everything is OK is, try to screenshare anything, or opening OBS and select the PipeWire source.
If XDPH is running, a Qt menu will pop up asking you what to share.

XDPH will work on other wlroots compositors, but features available only on Hyprland will not work (e.g., window sharing).

For a nuclear option, you can use this script and autostart it:

```sh
#!/bin/sh
sleep 1
killall -e xdg-desktop-portal-hyprland
killall xdg-desktop-portal
/usr/lib/xdg-desktop-portal-hyprland &
sleep 2
/usr/lib/xdg-desktop-portal &
```

Adjust the paths if they're incorrect.

## Share Picker Doesn't Use the System Theme

Try one or both:

```sh
dbus-update-activation-environment --systemd --all
systemctl --user import-environment QT_QPA_PLATFORMTHEME
```

If it works, add it to your config in autostarts.

## Using the KDE File Picker With XDPH

XDPH does not implement a file picker and uses the GTK one as a fallback by default (see `/usr/share/xdg-desktop-portal/hyprland-portals.conf`).
If you want to use the KDE file picker but let XDPH handle everything else, create a file `~/.config/xdg-desktop-portal/hyprland-portals.conf` with the following content:

```ini { filename="~/.config/xdg-desktop-portal/hyprland-portals.conf" }
[preferred]
default = hyprland;gtk
org.freedesktop.impl.portal.FileChooser = kde
```

You can read more about this in the [xdg-desktop-portal documentation in the Arch Wiki](https://wiki.archlinux.org/title/XDG_Desktop_Portal).
Note that some applications like Firefox may require additional configuration to use the KDE file picker.

## Debugging

If you get long app launch times, or screen sharing does not work, consult the logs.

```sh
systemctl --user status xdg-desktop-portal-hyprland
```

If you see a crash, it's likely you are missing either `qt6-wayland` or `qt5-wayland`.

If the portal does not autostart, does not function when manually started, and does not produce any error logs, it's very likely your XDG [environment variables](../../../configuring/core/environment-variables) are messed up.
Hyprland will set these for you by default; avoid overriding them unless you really know what you're doing.

## Configuration

Config file `~/.config/hypr/xdph.conf` allows for these variables:

### Screencopy

Variables in the `screencopy` category:

| Variable | Description | Type | Default |
| -- | -- | -- | -- |
| `max_fps`  | Maximum FPS of a screensharing session. `0` means no limit | int | `120` |
| `allow_token_by_default`  | If enabled, will tick the "Allow restore token" box by default | bool  | `false` |
| `custom_picker_binary`  | If non-empty, will use that **binary** as your share picker. Please note that it has to conform to the stdout selection layout of `hyprland-share-picker` | string  | `"hyprland-share-picker"` |
| `force_shm` | If enabled, will skip DMA-BUF and always use SHM for screensharing. SHM is slower than DMA-BUF (especially at high resolutions) but can work around DMA-BUF allocation failures on multi-GPU systems | bool | `false` |
| `cursor_mode` | Default cursor mode for clients that don't specify a mode (e.g., browsers). Any implemented mode for [XDG ScreenCast Portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.ScreenCast.html#org-freedesktop-portal-screencast-availablecursormodes), i.e. `1` - hidden or `2` - embedded. Defaults to protocol default (hidden) | int | `0` |

{{% details title="Example" closed="true" %}}

```ini { filename="~/.config/hypr/xdph.conf" }
screencopy {
    max_fps = 60
}
```

{{% /details %}}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall