Skip to content
nnthnnPublic

About

A fast, keyboard-driven workspace overview for Hyprland.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Hyprview logo

hyprview

A fast, keyboard-driven workspace overview for Hyprland.
Live window thumbnails, type-to-filter, and app icons — no compositor plugin required.

CI Website License: MIT Hyprland 0.55+

hyprview demo

hyprview runs as a small background daemon. On demand it puts up a fullscreen overlay showing every workspace with real window thumbnails, then lets you navigate, filter, focus, and move windows — all from the keyboard or, if you opt in, the mouse.

Features

  • Live window thumbnails via hyprland-toplevel-export-v1 (Hyprland only)
  • Workspace grid with named/numbered labels and windows that wrap to fill each card
  • Keyboard-first navigation with arrows or hjkl, plus 1–9 for direct card jumps
  • Tab / Shift+Tab window cycling across all workspaces, starting from the focused window
  • Type-to-filter across workspace names, window classes, and titles, with non-matches dimmed
  • Enter to act on the Tab-highlighted window, the single filter match, or the selected workspace
  • Move windows with m — send the active window to the selected workspace
  • Close windows with Delete, targeting the hovered window or single filter match
  • App icons on thumbnails, resolved from the icon theme and .desktop files
  • Hover tooltip with the app icon, name, class, and window title
  • Optional mouse support — hover to select, left-click to focus/switch, Shift+left-click to move, right-click to close
  • Config hot reload when the config file changes (or on SIGHUP)
  • Daemon lifetime with a single-instance lock and near-zero CPU while hidden
  • No process spawning — workspace/window operations go straight over the compositor's IPC socket

Requirements

  • Linux with a Wayland compositor that supports wlr-layer-shell
  • Hyprland 0.55+ for the full feature set, including live thumbnails
  • Sway works with reduced functionality: there are no live thumbnails, so windows are drawn as coloured placeholders with their app id (the same fallback as --no-preview)
  • No GTK, Qt, or other toolkit at runtime

Install

Each GitHub release includes a prebuilt x86_64 binary and a stable source tarball. The binary is dynamically linked against Wayland, Cairo, and Pango, so those runtime libraries must be installed.

Prebuilt binary

curl -LO https://github.com/nnthnn/hyprview/releases/latest/download/hyprview-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/nnthnn/hyprview/releases/latest/download/hyprview-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c hyprview-x86_64-unknown-linux-gnu.tar.gz.sha256
tar xzf hyprview-x86_64-unknown-linux-gnu.tar.gz
sudo install -Dm755 hyprview/hyprview /usr/local/bin/hyprview

Cargo

With a Rust toolchain installed:

cargo install --git https://github.com/nnthnn/hyprview --locked

Arch Linux

AUR publishing is paused while Arch restricts new accounts and package pushes, so build the tracked hyprview-git package locally:

git clone https://github.com/nnthnn/hyprview.git
cd hyprview/packaging/aur/hyprview-git
makepkg -si

From source

Build dependencies: a Rust toolchain, pkg-config, and the Wayland, Cairo, and Pango development headers.

# Arch
sudo pacman -S --needed base-devel rust wayland pango

# Debian / Ubuntu
sudo apt install cargo pkg-config libwayland-dev libpango1.0-dev

Then:

git clone https://github.com/nnthnn/hyprview.git
cd hyprview
cargo build --release

The binary is at target/release/hyprview.

Install it system-wide:

sudo install -Dm755 target/release/hyprview /usr/local/bin/hyprview

Or user-local (make sure ~/.local/bin is on your PATH):

install -Dm755 target/release/hyprview ~/.local/bin/hyprview

Usage

Start the daemon in the background:

hyprview &

Toggle the overlay from anywhere:

hyprview --toggle
# equivalent:
pkill -SIGUSR1 hyprview

Force a config reload:

pkill -SIGHUP hyprview

hyprview --toggle uses a PID lock file in $XDG_RUNTIME_DIR, so it can find the running daemon without a process lookup. Starting a second hyprview instance is a no-op — the existing instance keeps running.

To open the overlay immediately when the daemon starts, set show_on_startup = true in the [behavior] section of the config. This is handy when binding hyprview directly to an overview key instead of running it as an autostart daemon.

Hyprland config

Hyprland 0.55+ reads ~/.config/hypr/hyprland.lua. If you have migrated to the Lua config, add the daemon to your startup and bind a key to the toggle:

-- ~/.config/hypr/hyprland.lua
hl.on("hyprland.start", function()
    hl.exec_cmd("hyprview")
end)

hl.bind("SUPER + Tab", hl.dsp.exec_cmd("hyprview --toggle"))

Replace SUPER with your mainMod if you use a different modifier. If hyprview is installed somewhere Hyprland does not see on PATH (for example ~/.local/bin), use the full path in hl.exec_cmd. Hyprland loads hyprland.lua in preference to a legacy hyprland.conf, so the old exec-once/bind syntax will not take effect while a Lua config exists.

Sway config

Sway is auto-detected via SWAYSOCK/I3SOCK and runs in fallback mode without live thumbnails:

# ~/.config/sway/config
exec hyprview
bindsym $mod+Tab exec hyprview --toggle

Flags

Flag Description
--toggle Send SIGUSR1 to the running daemon and exit
--no-preview Skip thumbnails and draw coloured placeholder rectangles
--allow-mouse Enable mouse hover, click, and right-click support
-h, --help Print usage and exit
-V, --version Print the version and exit

CLI output is colourised when the matching stream is a terminal. Set NO_COLOR to any non-empty value to disable colour, for example when capturing logs.

--version prints just the release number for a build made from the matching vX.Y.Z tag. Local and in-between builds append the short commit id, for example hyprview 0.2.0 (a5a668f); uncommitted changes add -dirty.

Flags can be combined, for example:

hyprview --no-preview --allow-mouse &

Controls

Input Action
Arrow keys / hjkl Navigate the workspace grid
Tab / Shift+Tab Cycle the window highlight across all workspaces (starts from the focused window)
Enter Focus the highlighted window, the single filter match, or switch to the selected workspace
1–9 Jump to the 1st–9th workspace card in the grid
Type Filter workspaces, window classes, and titles
Backspace Delete the last filter character
m Move the active window to the selected workspace (when not filtering)
Delete Close the hovered window, or the single filter match
Escape Clear the Tab highlight, then the filter, then close the overlay
Mouse (with --allow-mouse) Hover to select and show the tooltip; left-click a window to focus it, a card to switch workspace, or outside to close; Shift+left-click to move the active window to the hovered workspace; right-click a window to close it

hjkl navigation is disabled while a filter is active; the arrow keys always work. Number keys only jump when the filter is empty.

Configuration

hyprview reads $XDG_CONFIG_HOME/hyprview/config.toml, falling back to ~/.config/hyprview/config.toml. Every key is optional. On first run the file is seeded from the bundled config.example.toml; an existing pre-rename ~/.config/hyprexpose/config.toml is migrated automatically.

The file is watched for changes and reloaded live. You can also send SIGHUP to force a reload. Unknown sections and keys are reported on stderr so typos don't silently fall back to defaults.

See docs/configuration.md for the full reference, or config.example.toml for the annotated file.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the short version, and docs/development.md for architecture notes, build and test commands, packaging, and the release process. Release notes are generated on the GitHub releases page.

License

MIT — see LICENSE.

hyprview began as a fork of hyprexpose by ThiagoAVicente. It has since diverged into its own project, adding type-to-filter, Tab cycling, app icons and tooltips, window closing, config hot reload, packaged releases, and this documentation and site.

About

A fast, keyboard-driven workspace overview for Hyprland.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Contributors

Languages