Show a chosen app window as the desktop background, behind all other windows.
Good to know
Several windows and layers need the Lua config; the hyprlang block handles one window. Class and title are exact matches.
hyprwinwrap
A Hyprland plugin that shows any window as your wallpaper
Unclaimed
Built by @gen3vra on GitHub. This page was written by @iluxav from public sources, last updated for 0.56v2 (2026-09-14), and may lag behind new releases.
Maintain hyprwinwrap? Claim itPin any app window, such as a terminal running cava or a video, behind your other windows as a desktop background on Hyprland.
What you can do with it
Bring the background window forward to use it, then send it back.
Before you upgrade
Newest first0.55v32026-06-06
The hyprlang plugin { hyprwinwrap { ... } } block is deprecated and the README says it will be removed; move to hl.plugin.hyprwinwrap.window() in Lua.
Read the evidence
Release history 5
0.56v22026-09-14
Size and place background windows to the exact pixel with fractional percentages or Lua math.
Details
Positions and sizes are no longer rounded, so values such as size_y = 100 * 1050 / 1080 land on an exact pixel. A failed window rule now shows a Hyprland notification. hyprpm.toml pins this build for Hyprland 0.56.0 to 0.56.2.
0.56v2; Hyprland 0.56.0 to 0.56.2.
Improved: Show a chosen app window as the desktop background,…
Seeded by @iluxav with Claude Code (canido)
0.562026-07-25
Keep a window as your background after upgrading to Hyprland 0.56.
Details
Builds against Hyprland 0.56.0. A background window no longer flashes when it closes.
0.56; for Hyprland 0.56.
Improved: Show a chosen app window as the desktop background,…
Seeded by @iluxav with Claude Code (canido)
Read the evidence
0.55v52026-06-18
Save battery: the background stops drawing while a fullscreen window covers the monitor.
Details
The background window is no longer rendered when the workspace on that monitor has a fullscreen window. Windows that suspend when hidden, such as kitty, keep updating after a workspace change. Groups 0.55v4 and 0.55v5.
0.55v5; this build is pinned for Hyprland 0.55.0 to 0.55.4.
Improved / inferred: Show a chosen app window as the desktop background,…Now works: Show a chosen app window as the desktop background,…
Seeded by @iluxav with Claude Code (canido)
0.55v32026-06-06
Stack several windows as backgrounds, for example a visualizer over part of the screen on top of a full-screen one.
Correction: Only the hyprlang plugin { hyprwinwrap { ... } } config is deprecated; showing a window as the background is not. It works through hl.plugin.hyprwinwrap.window() in Lua.
Correction: Retyped from deprecated: only the hyprlang plugin config block was deprecated; background windows work through the Lua config.
Details
New Lua config: hl.plugin.hyprwinwrap.window({ class, title, layer, pos_x, pos_y, size_x, size_y }) can be called several times, and layer sets which one draws on top. The focus toggle is now hl.plugin.hyprwinwrap.focus("<title-or-class>").
0.55v3; the Lua config needs a Hyprland version with Lua configuration. The hyprlang plugin block still works but is marked deprecated.
Improved: Show a chosen app window as the desktop background,…Improved: Bring the background window forward to use it, then…Behavior changed: Show a chosen app window as the desktop background,…
Seeded by @iluxav with Claude Code (canido)
0.55v22026-05-21
First release
First release
Show any window, such as a terminal running cava, as the desktop background on Hyprland.
Details
First releases (0.54, 0.55, 0.55v2). A plugin { hyprwinwrap { class, title, pos_x, pos_y, size_x, size_y } } block picks the window by exact class or title and places it behind everything, with position and size as percentages of the screen. The hyprwinwrap_interactivity dispatcher lets you focus and use that window.
Install with hyprpm add https://github.com/gen3vra/hyprwinwrap and hyprpm enable hyprwinwrap; needs Hyprland 0.54 or newer, with 0.55 supported from tag 0.55.
Added: Show a chosen app window as the desktop background,…Added: Bring the background window forward to use it, then…
Seeded by @iluxav with Claude Code (canido)