monbooru

module
v1.21.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 16, 2026 License: AGPL-3.0

README

Monbooru

Your own private, lightweight and fast booru.
Designed for organizing your local media collection, including AI-generated images (Stable Diffusion, ComfyUI, A1111/Forge). Supports ONNX models for local auto-tagging of your collection (WD14, JoyTag...). The app itself never touches the internet; online features (downloading from boorus or reverse image lookup) are handled by monloader, an optional companion.


Features

  • Tag-based gallery with folder tree, favorites, saved searches, collections, related-image suggestions, and rating tags (general / sensitive / questionable / explicit) with a SFW ceiling
  • Stable Diffusion metadata from A1111/Forge and ComfyUI: prompts, models, seeds, full workflows
  • Local ONNX auto-tagging (WD14 SwinV2, animetimm EVA02, JoyTag, Camie v2, or any compatible model) on CPU or GPU
  • Images, video, animated GIFs, plus CBZ/ZIP archives browsed as a single object with a built-in manga reader; animated hover previews on the grid
  • Search with wildcards, OR, exclusions, plus filters on folder, date, size, dimensions, category, generation recipe, and more
  • Keyboard-driven UI: contextual shortcuts on every page, from grid navigation to batch actions; press ? in-app for the full map
  • Tag management: merge duplicates, create aliases, implications, custom categories
  • Image relations: declared duplicates, alternates, version chains, derivatives; near-duplicate detection with a side-by-side review session and duplicate cleanup tools
  • Sources and provenance: multiple sources per image, artist commentary and note boxes, plus your own per-image notes and annotations
  • Batch operations on a selection or a whole search: delete, move, add/remove tags, auto-tag, set collection or source, toggle inbox/favorite, and more
  • File watcher that catches new, moved, and deleted files within seconds; multi-file browser upload; SHA-256 dedup so the same file under two paths is one image
  • Inbox workflow : new images land in the inbox for review
  • Multiple galleries in one instance, each with its own filesystem and database; per-gallery export/import; import data from supported booru applications
  • REST API for third-party integrations, with scoped bearer tokens, an OpenAPI spec, and built-in docs
  • Plugins and themes support: drop it in the plugins (or themes) folder and monbooru launches and supervises it for you
  • Monloader integration (optional) (monloader) pulls images and tags from supported boorus and galleries, and reverse-looks up your own images against boorus, similarity services (IQDB, SauceNAO), and the Hydrus Public Tag Repository to backfill tags and sources; when a matched post serves a better file than your local copy, one click replaces it in place; the PTR connection can also pull tag aliases and implications into your catalog
  • Optional password login

Technical overview

Monbooru compiles to a single self-contained binary (~21 MB, web assets embedded) with seven Go dependencies. Storage is one SQLite file per gallery: no database server, no cache layer, nothing else to run. Your collection stays ordinary files and folders on disk, the database and thumbnails live in a separate data directory, so removing monbooru leaves your images exactly where they were. The UI is server-rendered with no JS framework and no frontend build step.

The heavy features stay out of the core process: ONNX auto-tagging ships without a model and runs in a separate worker that unloads itself when idle, and everything online (downloading, reverse lookup) lives in the optional monloader companion, so monbooru itself never touches the internet. ffmpeg is an optional dependency for video and animated previews.


Monbooru is a self-hosted offline image organizer. Optional companions applications can be used for online features :

flowchart LR
    web["`- Any booru or gallery supported by gallery-dl
- Direct image URL`"]
    ptr["`Hydrus
Public Tag Repository`"]
    sender["`**monsender**
browser extension`"]
    loader["`**monloader**
downloader`"]
    booru(["`**monbooru**
Your self-hosted booru`"])

    web -->|browse| sender
    sender -->|send URL| loader
    web -->|paste URL| loader
    loader -->|push images, tags, source| booru

    booru -.->|lookup by hash| loader
    loader -.->|reverse lookup: md5 + similarity| web
    ptr <-.->|"`sync: sha256 tags + aliases + implications
contribute back`"| loader

    classDef hub  fill:#9d2235,stroke:#ef8f99,stroke-width:3px,color:#ffffff;
    classDef tool fill:#1a1818,stroke:#9d2235,stroke-width:1.5px,color:#e8e4e2;
    classDef src  fill:#1a1818,stroke:#a09898,stroke-width:1px,color:#a09898;

    class booru hub;
    class sender,loader tool;
    class web,ptr src;
  • monbooru : this application; organizes, tags, and serves your collection.
  • monloader : downloader; fetches files and per-post metadata (via gallery-dl) and pushes them into a monbooru gallery over the REST API; also answers monbooru's reverse lookups (boorus, IQDB/SauceNAO, Hydrus PTR) and source refetches.
  • monsender : browser extension; sends the URL of the page you're currently browsing to monloader.
  • monbooru-plugins : community registry for third-party plugins and themes.

Quick start (Docker)

Edit the volume paths in docker/docker-compose.yml, then docker compose up -d. The app is available at http://localhost:8455.

Quick start (Binaries)

Download a build for your system from the releases, unpack it, and run it. The app is available at http://localhost:8455.

Downloads come in two shapes:

  • lite is a single binary.
  • bundled carries ffmpeg and the ONNX Runtime beside it, so video thumbnails and local CPU auto-tagging work with nothing else installed.

Beside the portable archives, Linux bundled builds also ship as an AppImage and as a Flatpak.

See the monbooru documentation for help. In-app, type system: in the search bar for the syntax cheat-sheet and press ? for the keyboard shortcuts; the footer's help link opens the documentation.


Warning

Intended for local network use. This project is not designed for direct exposure to the public internet.


Acknowledgements

This section covers monbooru and its companion repos (monloader, monsender, mondocs, monbooru-plugins).

Thanks to @gary-host-laptop and @CeareDelafont for sustained contributions over time. Every shipped contribution is credited in the release that ships it; see CONTRIBUTING.

This project is built on the work of others:

  • htmx powers the server-rendered UI.
  • SQLite, through the pure-Go modernc.org/sqlite driver, stores each gallery.
  • ONNX Runtime, through onnxruntime_go, runs the auto-tagger. The models in the bundled catalog are the work of SmilingWolf (WD SwinV2 v3), animetimm (EVA02), fancyfeast (JoyTag), and Camais03 (Camie Tagger v2).
  • ffmpeg decodes video for thumbnails and hover previews; the bundled downloads carry a trimmed build of it from ffmpeg-builds, statically linked with libwebp and dav1d.
  • monloader is mostly a wrapper for gallery-dl, which does the actual scraping. Reverse lookups by image similarity are answered by IQDB and SauceNAO; md5 lookups by the boorus themselves. The PTR tag lookup syncs against the Hydrus Public Tag Repository (PTR) via Hydrus Network's repository protocol; the tags, aliases, and implications it serves are the work of the hydrus community.
  • monsender's in-page image detection uses code from ushiro by gary-host-laptop and behind! by kubuzetto, originally under MPL-2.0.
  • The mondocs site is built with Hugo.

The full Go dependency lists are in each repo's go.mod.

The sample images in the screenshots, here, in the companion repos, and in the documentation, were downloaded from Danbooru and are the work of their respective artists, who retain all rights. They appear only to demonstrate the app; the repositories' license doesn't apply to them.

Directories

Path Synopsis
cmd
monbooru command
Command monbooru is the binary: it reads the config, resolves the profile (server, desktop or portable), opens the galleries, starts the HTTP server and the desktop integration around it, and handles the subcommands and the restart-in-place the tray and the Settings page ask for.
Command monbooru is the binary: it reads the config, resolves the profile (server, desktop or portable), opens the galleries, starts the HTTP server and the desktop integration around it, and handles the subcommands and the restart-in-place the tray and the Settings page ask for.
internal
api
Package api implements the /api/v1/ REST handlers for monbooru.
Package api implements the /api/v1/ REST handlers for monbooru.
config
Package config is the TOML file, the environment overrides that layer on top of it, the defaults underneath, the validation between them, and the atomic save back.
Package config is the TOML file, the environment overrides that layer on top of it, the defaults underneath, the validation between them, and the atomic save back.
counts
Package counts owns the whole-library tallies more than one caller divides by, and caches them per gallery.
Package counts owns the whole-library tallies more than one caller divides by, and caches them per gallery.
db
Package db owns the SQLite handles and the schema.
Package db owns the SQLite handles and the schema.
desktop
Package desktop resolves the per-OS locations and the one-time startup behaviour the -desktop profile needs.
Package desktop resolves the per-OS locations and the one-time startup behaviour the -desktop profile needs.
fsx
Package fsx holds the filesystem primitives more than one package needs and none of them owns: it sits below every domain package so a caller as low as internal/config can reach it without inverting the import order.
Package fsx holds the filesystem primitives more than one package needs and none of them owns: it sits below every domain package so a caller as low as internal/config can reach it without inverting the import order.
gallery
Package gallery owns the files under a gallery root: ingest, thumbnails, hashing, placement and the path containment every other package files through.
Package gallery owns the files under a gallery root: ingest, thumbnails, hashing, placement and the path containment every other package files through.
galleryio
Package galleryio moves a whole gallery in or out: export, import, merge, and transfer between two live galleries, in each format the app ships.
Package galleryio moves a whole gallery in or out: export, import, merge, and transfer between two live galleries, in each format the app ships.
galleryio/compatibility
Package compatibility translates foreign gallery exports (zipped Hydrus exports, ...) into the same in-memory shape the monbooru-native light import consumes.
Package compatibility translates foreign gallery exports (zipped Hydrus exports, ...) into the same in-memory shape the monbooru-native light import consumes.
jobs
Package jobs is the one background job at a time: the state machine, its progress and cancellation, and the chunking loop the long runs walk their work in.
Package jobs is the one background job at a time: the state machine, its progress and cancellation, and the chunking loop the long runs walk their work in.
library
Package library owns one open gallery: its paths, its database, the services and caches that hang off them, and the background work that keeps them fresh.
Package library owns one open gallery: its paths, its database, the services and caches that hang off them, and the background work that keeps them fresh.
logx
Package logx is a thin level gate over the stdlib log package.
Package logx is a thin level gate over the stdlib log package.
lookup
Package lookup holds the scheduled hash lookup's retry ladder, the "due" predicate, and the per-image attempt history.
Package lookup holds the scheduled hash lookup's retry ladder, the "due" predicate, and the per-image attempt history.
markup
Package markup renders the bracket vocabulary that annotation bodies, operator notes and artist commentary carry: a few inline marks plus links to a tag search, to another image, or off-site.
Package markup renders the bracket vocabulary that annotation bodies, operator notes and artist commentary carry: a few inline marks plus links to a tag search, to another image, or off-site.
metadata
Package metadata reads what a file says about itself: Stable Diffusion parameters from A1111 and Forge, ComfyUI workflows in both the API and the workflow shape, EXIF, and ComicInfo out of an archive.
Package metadata reads what a file says about itself: Stable Diffusion parameters from A1111 and Forge, ComfyUI workflows in both the API and the workflow shape, EXIF, and ComicInfo out of an archive.
models
Package models is the vocabulary the other packages share: the row structs, the column list and scanner every image read goes through, and the job and origin constants more than one package names.
Package models is the vocabulary the other packages share: the row structs, the column list and scanner every image read goes through, and the job and origin constants more than one package names.
monloader
Package monloader is monbooru's outbound half of the pair: the HTTP client that talks to the operator's monloader instance and nothing else.
Package monloader is monbooru's outbound half of the pair: the HTTP client that talks to the operator's monloader instance and nothing else.
plugins
Package plugins supervises the child processes monbooru launches for operator-installed plugins.
Package plugins supervises the child processes monbooru launches for operator-installed plugins.
procx
Package procx holds the child-process primitives more than one package needs and none of them owns.
Package procx holds the child-process primitives more than one package needs and none of them owns.
relations
Package relations manages the operator-declared graph between images: duplicate groups, alternate groups, directed version chains, directed derivative trees, and the "not related" rejection set.
Package relations manages the operator-declared graph between images: duplicate groups, alternate groups, directed version chains, directed derivative trees, and the "not related" rejection set.
search
Package search implements the Monbooru query language parser and SQL executor.
Package search implements the Monbooru query language parser and SQL executor.
searchkw
Package searchkw declares the search query language's filter-keyword vocabulary as a leaf data package.
Package searchkw declares the search query language's filter-keyword vocabulary as a leaf data package.
tags
Package tags owns the tag catalog and every image's membership in it: the tags themselves, their categories, aliases, implications and the image_tags rows that apply them.
Package tags owns the tag catalog and every image's membership in it: the tags themselves, their categories, aliases, implications and the image_tags rows that apply them.
upgrade
Package upgrade holds the "this source serves a file we do not have" predicate in its two spellings - one over a loaded origin, one over an image_sources row - so the detail page's upgrade action, the replace handler's gate, and the `upgrade:` filter cannot disagree about what counts as a candidate.
Package upgrade holds the "this source serves a file we do not have" predicate in its two spellings - one over a loaded origin, one over an image_sources row - so the detail page's upgrade action, the replace handler's gate, and the `upgrade:` filter cannot disagree about what counts as a candidate.
web
Package web is the HTTP transport: the mux, the handlers, the templates they render and the session, CSRF and rating-cookie plumbing around them.
Package web is the HTTP transport: the mux, the handlers, the templates they render and the session, CSRF and rating-cookie plumbing around them.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL