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/virtual-gpu.md

View on GitHub
<!-- source: https://wiki.hypr.land/configuring/extra/virtual-gpu -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->

---
weight: 20
title: Virtual GPU
---

<!-- TODO: maybe move to core or core/advanced? it is essential for laptops -->

## General

If you happen to be in possession of a GPU that falls into one of these categories:
- Intel Arc Pro card
- Intel laptop integrated graphics
- NVIDIA Workstation or Server card
- NVIDIA RTX 2000 series card
- AMD Radeon Instinct card

It is very likely that your graphics card supports virtual partitioning, either through the use of mediated devices or SR-IOV.
The means of enabling this partitioning is beyond the scope of this wiki, and is very different between vendors.

As an example, once partitioning is enabled, this is what an RTX A5000 card will create:

```console
# lspci -d 10de:
01:00.0 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:00.4 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:00.5 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:00.6 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:00.7 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.0 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.1 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.2 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.3 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.4 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.5 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.6 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:01.7 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.0 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.1 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.2 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.3 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.4 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.5 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.6 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:02.7 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:03.0 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:03.1 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:03.2 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
01:03.3 3D controller: NVIDIA Corporation GA102GL [RTX A5000] (rev a1)
```

You may want to pass through one of these virtual GPU partitions, also called vGPU, in a virtual machine to run Hyprland with hardware acceleration.

> [!NOTE]
> The following procedures **do not concern paravirtualized drivers like Virtio-GPU**.
>
> Virtio-GPU is not a virtual partition of your hardware device, but an entirely software-emulated device that forwards its duty to your host GPU.
> Having been developed for this purpose, it provides an emulated screen output.
> Therefore you can use Hyprland normally with it, with no extra effort required.

## Running Hyprland on vGPU

Hyprland requires by default that your graphics card has **at least one display output**.

However, for all vendors, vGPUs are render-only cards and have no emulated output on Linux.
That is because they are targeting VDI infrastructures, 3D rendering, encoding and compute use cases that are all remote.
This is also suggested by their prefix "3D controller", instead of "VGA compatible controller".

**To allow Hyprland to run** on a graphics card **with no output, you must enable the** `AQ_NO_KMS_REQUIREMENT` environment flag when running Hyprland:

```lua
hl.env("AQ_NO_KMS_REQUIREMENT", "1")
```

### Usage of both a GPU and vGPU

> [!WARNING]
> Users of QEMU hypervisor that are both doing a vGPU passthrough and exposing a Virtio-GPU device in their virtual machine are concerned by this section.

Most hardware and paravirtualized drivers will expose the same graphics card twice under the `/dev/dri` directory.
One node will be globally accessible and provide render capabilities, while the other will be privileged and expose one or more display outputs.

```console
$ ls -lh /dev/dri/
total 0
drwxr-xr-x  2 root root         80 Apr 20 07:01 by-path/
crw-rw----+ 1 root video  226,   1 Apr 20 07:01 card1           # KMS card with outputs
crw-rw-rw-  1 root render 226, 128 Apr 20 07:01 renderD128      # DRM card, render-only
```

Hyprland will, by default, only select nodes on the system with display outputs and ignore the `render` node.
But with `AQ_NO_KMS_REQUIREMENT` lifting this need, the `render` node becomes a suitable candidate.

If you happen to be using both a virtual GPU and a hardware GPU on the same virtual machine, **you must set the `AQ_DRM_DEVICES` flag**.
This flag is described and explained in [Multi-GPU](../multi-gpu):

```lua
hl.env("AQ_NO_KMS_REQUIREMENT", "1")
hl.env("AQ_DRM_DEVICES", "/dev/dri/card0:/dev/dri/card1")
```

In practice, there is no guaranteed order of which node will be used as the primary renderer in a virtual machine.
It is important that you manually decide the priority.

> [!WARNING]
> Some hypervisors can expose PCI topologies that can be understood differently at each start.
> To be sure of setting the correct node, refer to [Multi-GPU section on consistent device paths](../multi-gpu#creating-consistent-device-paths-for-specific-cards) for renaming the nodes and making your configuration consistent across reboots.

## Accessing the virtual display

When Hyprland starts without any display output, it will initialize a headless output called `HEADLESS-0` with a `1920x1080@60Hz` resolution and framerate, that you can alter in your usual `hyprland.lua` file.

You have to use a remote desktop server, supporting the wlroots capture protocol, for accessing the display and interacting with Hyprland.

The following servers are known to be supported:
- [Sunshine/Moonlight](https://app.lizardbyte.dev/Sunshine/)
- [Apollo/Artemis(Moonlight Noir)](https://github.com/ClassicOldSong/Apollo)
- [Wayvnc](https://github.com/any1/wayvnc)

Once you start Hyprland, you can start your server remotely using `hyprctl` on the guest (See [Using hyprctl](../../core/advanced-configuration/using-hyprctl))

```bash
hyprctl --instance 0 eval 'hl.exec_cmd("Sunshine")'
```

The remote display server should be running below the Hyprland process to inherit all its environment variables.
Otherwise it will not find your headless display.

If everything is configured and working correctly, you can set your server in your `hyprland.lua` file to be autostarted (see [Autostart](../../core/autostart)).
For example:

```lua
hl.on("hyprland.start", function()
    hl.exec_cmd("Sunshine")
end)
```

Congratulations on obtaining your very own virtual Hyprland desktop.
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 CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall