pax
7d195558f6
Group B of the popout viewport work. The v0.2.2 viewport compute swap
fixed the big aspect-ratio failures (width-anchor ratchet, asymmetric
clamps, manual-resize destruction) but kept a minor "recompute from
current state every nav" shortcut that accumulated 1-2px of downward
drift across long navigation sessions. This commit replaces that
shortcut with a true persistent viewport that's only updated by
explicit user action, not by reading our own dispatch output back.
The viewport (center_x, center_y, long_side) is now stored as a
field on FullscreenPreview, seeded from `_pending_*` on first fit
after open or F11 exit, and otherwise preserved across navigations.
External moves/resizes are detected via a `_last_dispatched_rect`
cache: at the start of each fit, the current `hyprctl clients -j`
position is compared against the last rect we dispatched, and if
they differ by more than `_DRIFT_TOLERANCE` (2px) the user is
treated as having moved the window externally and the viewport
adopts the new state. Sub-pixel rounding stays inside the tolerance
and the viewport stays put.
`_exit_fullscreen` is simplified — no more re-arming the
`_first_fit_pending` one-shots. The persistent viewport already
holds the pre-fullscreen center+long_side (fullscreen entry/exit
runs no fits, so nothing overwrites it), and the deferred fit after
`showNormal()` reads it directly. Side benefit: this fixes the
legacy F11-walks-toward-saved-top-left bug 1f as a free byproduct.
## The moveEvent/resizeEvent gate (load-bearing — Group B v1 broke
## without it)
First implementation of Group B added moveEvent/resizeEvent handlers
to capture user drags/resizes into the persistent viewport on the
non-Hyprland Qt path. They were guarded with a `_applying_dispatch`
reentrancy flag set around the dispatch call. **This broke every
navigation, F11 round-trip, and external drag on Hyprland**, sending
the popout to the top-left corner.
Two interacting reasons:
1. On Wayland (Hyprland included), `self.geometry()` returns
`QRect(0, 0, w, h)` for top-level windows. xdg-toplevel doesn't
expose absolute screen position to clients, and Qt6's wayland
plugin reflects that by always reporting `x=0, y=0`. So the
handlers wrote viewport center = `(w/2, h/2)` — small positive
numbers far from the actual screen center.
2. The `_applying_dispatch` reentrancy guard works for the
synchronous non-Hyprland `setGeometry()` path (moveEvent fires
inside the try-block) but does NOT work for the async hyprctl
dispatch path. `subprocess.Popen` returns instantly, the
`try/finally` clears the guard, THEN Hyprland processes the
dispatch and sends a configure event back to Qt, THEN Qt fires
moveEvent — at which point the guard is already False. So the
guard couldn't suppress the bogus updates that Wayland's
geometry handling produces.
Fix: gate both moveEvent and resizeEvent's viewport-update branches
with `if os.environ.get("HYPRLAND_INSTANCE_SIGNATURE"): return` at
the top. On Hyprland, the cur-vs-last-dispatched comparison in
`_derive_viewport_for_fit` is the sole external-drag detector,
which is what it was designed to be. The non-Hyprland branch stays
unchanged so X11/Windows users still get drag-and-resize tracking
via Qt events (where `self.geometry()` is reliable).
## Verification
All seven manual tests pass on the user's Hyprland session:
1. Drift fix (P↔L navigation cycles): viewport stays constant, no
walking toward any corner
2. Super+drag externally then nav: new dragged position picked up
by the cur-vs-last-dispatched comparison and preserved
3. Corner-resize externally then nav: same — comparison branch
adopts the new long_side
4. F11 same-aspect round-trip: window lands at pre-fullscreen center
5. F11 across-aspect round-trip: window lands at pre-fullscreen
center with the new aspect's shape
6. First-open from saved geometry: works (untouched first-fit path)
7. Restart persistence across app sessions: works (untouched too)
## Files
`booru_viewer/gui/preview.py` only. ~239 added, ~65 removed:
- `_DRIFT_TOLERANCE = 2` constant at module top
- `_viewport`, `_last_dispatched_rect`, `_applying_dispatch` fields
in `FullscreenPreview.__init__`
- `_build_viewport_from_current` helper (extracted from old
`_derive_viewport_for_fit`)
- `_derive_viewport_for_fit` rewritten with three branches:
first-fit seed, defensive build, persistent + drift check
- `_fit_to_content` wraps dispatch with `_applying_dispatch` guard,
caches `_last_dispatched_rect` after dispatch
- `_exit_fullscreen` simplified (no more `_first_fit_pending`
re-arm), invalidates `_last_dispatched_rect` so the post-F11 fit
doesn't false-positive on "user moved during fullscreen"
- `moveEvent` added (gated to non-Hyprland)
- `resizeEvent` extended with viewport update (gated to non-Hyprland)
|
||
|---|---|---|
| booru_viewer | ||
| screenshots | ||
| themes | ||
| .gitattributes | ||
| .gitignore | ||
| CHANGELOG.md | ||
| LICENSE | ||
| README.md | ||
| booru-viewer.spec | ||
| icon.ico | ||
| icon.png | ||
| installer.iss | ||
| pyproject.toml | ||
README.md
booru-viewer
A booru client for people who keep what they save and rice what they run.
Qt6 desktop app for Linux and Windows. Browse, search, and archive Danbooru, e621, Gelbooru, and Moebooru. Fully themeable.
If you find this useful, consider buying me a coffee:
Screenshots
Windows 11 — Light Theme
Windows 11 — Dark Theme (auto-detected)
Windows 10 — Light Theme
Windows 10 — Dark Theme (auto-detected)
Linux — Styled via system Qt6 theme
Supports custom styling via custom.qss — see Theming.
Why booru-viewer
There are a few other desktop booru clients worth knowing about. ahoviewer is the most mature one. Grabber is the most popular. Hydrus is a full local-first media tagging system that happens to import from boorus, which puts it in a different category entirely.
ahoviewer is the closest to what this is, but its "save" opens a file dialog and dumps the file into a folder you organize yourself. Most ricers who want a daily-driver booru client end up wrestling with Hydrus, scripting Grabber from the CLI, or just keeping browser tabs open.
Two things are different here:
You bookmark and save like you do in a web browser. Bookmark is a pointer. Save actually writes the file. Library items live as 12345.jpg in ~/.local/share/booru-viewer/saved/ and you can open them in Thunar or whatever you use. The difference from ahoviewer is that the tags, source, score, and folder all live in SQLite next to the files. You don't have to invent filenames or build a folder hierarchy. Search by tag, find what you saved. Your images are normal files on disk. If the database breaks, your saves don't go with it.
It's built for tiling Wayland. Hyprland integration with opt-out env vars if you want your own window rules. Wayland app_id set so windowrule = float, class:^(booru-viewer)$ works. The whole UI is themeable through a @palette preprocessor. Six bundled themes ship: Catppuccin, Nord, Gruvbox, Tokyo Night, Everforest, Solarized. Each comes in rounded and square. No other client in the space cares whether you're on GNOME or Hyprland.
Features
booru-viewer has three tabs that map to three commitment levels: Browse for live search against booru APIs, Bookmarks for posts you've starred for later, Library for files you've actually saved to disk.
Browsing
- Supports Danbooru, e621, Gelbooru, and Moebooru
- Auto-detect site API type — just paste the URL
- Tag search with autocomplete, history dropdown, and saved searches
- Rating and score filtering (server-side
score:>=N) - Media type filter — dropdown: All / Animated / Video / GIF / Audio
- Blacklisted tags and posts (client-side filtering with backfill)
- Thumbnail grid with keyboard navigation, multi-select (Ctrl/Shift+Click, Ctrl+A), bulk context menus, and drag thumbnails out as files
- Infinite scroll — optional, auto-loads more posts at bottom
- Start from page — jump to any page number on search
- Page cache — prev/next loads from memory, no duplicates
- Copy File to Clipboard — Ctrl+C, works for images and videos
Preview
- Image viewer with zoom (scroll wheel), pan (drag), and reset (middle click)
- GIF animation, Pixiv ugoira auto-conversion (zip to animated GIF)
- Animated PNG/WebP auto-conversion to GIF
- Video playback via mpv (MP4, WebM, MKV) with play/pause, seek, volume, mute, and seamless looping
- Info panel with post details, date, clickable tags, and filetype
- Preview toolbar — Bookmark, Save, BL Tag, BL Post, and Popout buttons above the preview panel
Popout Viewer
- Right-click preview → "Popout" or click the Popout button in the preview toolbar
- Arrow keys /
h/j/k/lnavigate posts (including during video playback) ,/.seek 3 seconds in videos,Spacetoggles play/pause- Floating overlay UI — toolbar and video controls auto-hide after 2 seconds, reappear on mouse move
F11toggles fullscreen/windowed,Ctrl+Hhides all UI,Ctrl+Pprivacy screen- Window auto-sizes to content aspect ratio; state persisted across sessions
- Hyprland:
keep_aspect_ratioprop locks window to content proportions - Bidirectional sync — clicking posts in the main grid updates the popout
- Video position and player state synced between preview and popout
Bookmarks
- Bookmark posts you might want later — lightweight pointers in the database, like clicking the star in your browser
- Group bookmarks into folders, separate from Library's folders
- Search bookmarks by tag
- Bulk save, unbookmark, or remove from the multi-select context menu
- Import/export bookmarks as JSON
- Unbookmark from grid, preview, or popout
Library
- Save posts you want to keep — real files on disk in
saved/, named by post ID, browsable in any file manager - One-click promotion from bookmark to library when you decide to commit
- Tag search across saved metadata — type to filter by indexed tags, no filename conventions required
- On-disk folder organization with configurable library directory and folder sidebar — save unsorted or to a named subfolder
- Sort by date, name, or size
- Video thumbnail generation (ffmpeg if available, placeholder fallback)
- Unsave from grid, preview, and popout (only shown when post is saved)
- Unreachable directory detection
Search
- Inline history dropdown inside the search bar
- Saved searches with management dialog
- Click empty search bar to open history
- Session cache mode clears history on exit (keeps saved searches)
Install
Windows
Download booru-viewer-setup.exe from Releases and run the installer. It installs to AppData with Start Menu and optional desktop shortcuts. To update, just run the new installer over the old one — your data in %APPDATA%\booru-viewer\ is preserved.
Windows 10 dark mode is automatically detected and applied.
Linux
Requires Python 3.11+ and pip. Most distros ship Python but you may need to install pip and the Qt6 system libraries.
Arch / CachyOS:
sudo pacman -S python python-pip qt6-base mpv ffmpeg
Ubuntu / Debian (24.04+):
sudo apt install python3 python3-pip python3-venv mpv libmpv-dev ffmpeg
Fedora:
sudo dnf install python3 python3-pip qt6-qtbase mpv mpv-libs-devel ffmpeg
Then clone and install:
git clone https://git.pax.moe/pax/booru-viewer.git
cd booru-viewer
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
Run it:
booru-viewer
Or without installing: python3 -m booru_viewer.main_gui
Desktop entry: To add booru-viewer to your app launcher, create ~/.local/share/applications/booru-viewer.desktop:
[Desktop Entry]
Name=booru-viewer
Exec=/path/to/booru-viewer/.venv/bin/booru-viewer
Icon=/path/to/booru-viewer/icon.png
Type=Application
Categories=Graphics;
Hyprland integration
I daily-drive booru-viewer on Hyprland and I've baked in my own opinions on
how the app should behave there. By default, a handful of hyprctl dispatches
run at runtime to:
- Restore the main window's last floating mode + dimensions on launch
- Restore the popout's position, center-pin it around its content during navigation, and suppress F11 / fullscreen-transition flicker
- "Prime" Hyprland's per-window floating cache at startup so a mid-session toggle to floating uses your saved dimensions
- Lock the popout's aspect ratio to its content so you can't accidentally stretch mpv playback by dragging the popout corner
If you're a ricer with your own windowrules targeting class:^(booru-viewer)$
and you'd rather the app keep its hands off your setup, there are two
independent opt-out env vars:
BOORU_VIEWER_NO_HYPR_RULES=1— disables every in-code hyprctl dispatch except the popout'skeep_aspect_ratiolock. Use this if you want app-side window management out of the way but you still want the popout to size itself to its content.BOORU_VIEWER_NO_POPOUT_ASPECT_LOCK=1— independently disables the popout's aspect ratio enforcement. Useful if you want to drag the popout to whatever shape you like (square, panoramic, monitor-aspect, whatever) and accept that mpv playback will letterbox or stretch to match.
For the full hands-off experience, set both:
[Desktop Entry]
Name=booru-viewer
Exec=env BOORU_VIEWER_NO_HYPR_RULES=1 BOORU_VIEWER_NO_POPOUT_ASPECT_LOCK=1 /path/to/booru-viewer/.venv/bin/booru-viewer
Icon=/path/to/booru-viewer/icon.png
Type=Application
Categories=Graphics;
Or for one-off launches from a shell:
BOORU_VIEWER_NO_HYPR_RULES=1 booru-viewer
Dependencies
- Python 3.11+
- PySide6 (Qt6)
- httpx
- Pillow
- python-mpv
- mpv (system package on Linux, bundled DLL on Windows)
Keybinds
Grid
| Key | Action |
|---|---|
Arrow keys / h/j/k/l |
Navigate grid |
Ctrl+A |
Select all |
Ctrl+Click / Shift+Click |
Multi-select |
Home / End |
Jump to first / last |
| Scroll tilt left / right | Previous / next thumbnail (one cell) |
Ctrl+C |
Copy file to clipboard |
| Right click | Context menu |
Preview
| Key | Action |
|---|---|
| Scroll wheel | Zoom (image) / volume (video) |
| Scroll tilt left / right | Previous / next post |
Middle click / 0 |
Reset view |
Arrow keys / h/j/k/l |
Navigate posts |
, / . |
Seek 3s back / forward (video) |
Space |
Play / pause (video, hover to activate) |
| Right click | Context menu (bookmark, save, popout) |
Popout
| Key | Action |
|---|---|
Arrow keys / h/j/k/l |
Navigate posts |
| Scroll tilt left / right | Previous / next post |
, / . |
Seek 3s (video) |
Space |
Play / pause (video) |
| Scroll wheel | Volume up / down (video) |
F11 |
Toggle fullscreen / windowed |
Ctrl+H |
Hide / show UI |
Ctrl+P |
Privacy screen |
Escape / Q |
Close popout |
Global
| Key | Action |
|---|---|
Ctrl+P |
Privacy screen |
F11 |
Toggle fullscreen |
Adding Sites
File > Manage Sites. Enter a URL, click Auto-Detect, and save.
API credentials are optional — needed for Gelbooru and rate-limited sites.
Tested Sites
- danbooru.donmai.us
- gelbooru.com
- rule34.xxx
- safebooru.donmai.us
- safebooru.org
- e621.net
Theming
The app uses your OS native theme by default. To customize, copy a .qss file from the themes/ folder to your data directory as custom.qss:
- Linux:
~/.local/share/booru-viewer/custom.qss - Windows:
%APPDATA%\booru-viewer\custom.qss
A template is also available in Settings > Theme > Create from Template.
Included Themes
Each theme ships in two variants: *-rounded.qss (4px corner radius) and *-square.qss (no corner radius except radio buttons). Same colors, different geometry.
Settings
- General — page size, thumbnail size, default site, default rating/score, prefetch mode (Off / Nearby / Aggressive), infinite scroll, popout monitor, file dialog platform
- Cache — max cache size, max thumbnail cache, auto-evict, clear cache on exit (session-only mode)
- Blacklist — tag blacklist with toggle, post URL blacklist
- Paths — data directory, cache, database, configurable library directory
- Theme — custom.qss editor, template generator, CSS guide
- Network — connection log showing all hosts contacted this session
Data Locations
| Linux | Windows | |
|---|---|---|
| Database | ~/.local/share/booru-viewer/booru.db |
%APPDATA%\booru-viewer\booru.db |
| Cache | ~/.local/share/booru-viewer/cache/ |
%APPDATA%\booru-viewer\cache\ |
| Library | ~/.local/share/booru-viewer/saved/ |
%APPDATA%\booru-viewer\saved\ |
| Theme | ~/.local/share/booru-viewer/custom.qss |
%APPDATA%\booru-viewer\custom.qss |
To back up everything: copy saved/ for the files themselves and booru.db for bookmarks, folders, and tag metadata. The two are independent — restoring one without the other still works. The saved/ folder is browsable on its own in any file manager, and the database can be re-populated from the booru sites for any post IDs you still have on disk.
Privacy
booru-viewer makes no connections except to the booru sites you configure. There is no telemetry, analytics, update checking, or phoning home. All data stays local on your machine.
Every outgoing request is logged in Settings > Network so you can verify this yourself — you will only see requests to the booru API endpoints and CDNs you chose to connect to.
License
MIT