Hydrus Network

Last reviewed Sep 13, 2026 · 924 words

Hydrus Network is a desktop database that swallows your files, renames them to their SHA-256 hash, and never gives them back in a form you would browse with a file manager. That single design decision explains everything else about it: the tag search that makes a 500,000-image collection usable, the Hard difficulty rating, and the number of people who install it, panic at the interface, and uninstall it a week later. If you want phone backup and face recognition, stop here and go to Immich. If you want a searchable archive of images collected from the web, keep reading.

It is a client, and the "server" is optional

The name suggests a web app you run on a NAS. It is not. The client is a Qt desktop program for Windows, Linux and macOS that owns a set of SQLite databases and a file store split into 256 hashed subdirectories. A self-hoster runs it on a workstation, or on a headless box with a virtual display, and points the database at fast storage. The separate hydrus server exists so several clients can share a tag repository or a file repository, which is how the Public Tag Repository (PTR) works. Most single users never run the server component at all.

The catalogue lists 1,024 MB as the minimum, and that is optimistic for anything beyond a starter collection. The client keeps several database files that grow with your mappings; syncing the PTR pulls in tag mappings for many millions of files, and the database for that alone runs to tens of gigabytes on disk and days of processing on a spinning drive. Put the databases on an SSD, budget 4 GB of RAM for the process once you are past 100,000 files, and skip the PTR entirely unless the bulk of your collection comes from sites it covers.

Tags are the whole product

A tag in hydrus is namespace:value, so creator:someone, series:something, character:another. Search is a boolean composition of those plus system predicates: system:filesize > 2MB, system:num_tags < 5, system:duplicate .... The interface exposes all of that through a tag autocomplete box that feels hostile for the first hour and indispensable after the first week.

Tagging at scale comes from three places. Downloaders pull posts and their tags from booru-style sites via parsers, and the community maintains parsers for the big ones; a Danbooru instance you run yourself can be a source too. Sidecar files (.txt or .json alongside each file) import tags from an existing collection. The PTR contributes tags others have added to files with the same hash.

The duplicate filter earns the install on its own

Hydrus computes perceptual hashes on import and queues potential duplicate pairs for you to resolve in a side-by-side filter, one pair at a time, with keyboard shortcuts for "this is better", "same quality", "not duplicates" and "alternates". It merges tags and URLs to the survivor and can delete the loser. For anyone who has re-saved the same image at 3 different resolutions across 10 years, this is the feature that justifies the learning curve. Nothing in the photo-server category does duplicate review this carefully; PhotoPrism flags exact matches, not near-matches you adjudicate.

Weekly releases, and the update discipline that implies

The developer ships a new version roughly weekly, with release notes that are long and honest. Updates are safe if you follow two rules the documentation repeats: back up the database directory before you update (the client can do this from its menu), and never skip more than a handful of versions at once, because the database migrations are written to run in sequence. The help folder shipped with each release is the actual manual; read the getting-started section before importing anything, because the choices about where the database and files live are awkward to change later.

The WTFPL licence and the 3,188 stars understate the project's persistence: one person has developed it continuously since 2011. The Client API on port 45869 has a small ecosystem of companion tools, notably Hydrus Companion (a browser extension for sending pages to the downloader) and a few gallery front-ends for viewing your collection from a phone over the API.

Who should not run it

Anyone whose media is family photos. Hydrus has no album concept in the sense you expect, no map view, no face recognition and no phone upload, and the photo server category is full of tools that do those well. Anyone who wants to keep an existing folder structure, because hydrus will move or copy every file into its own hash-named store. There is no simplified mode for anyone who dislikes dense interfaces.

What I'd do

Install the client on a Linux box with the databases on NVMe and the file store on whatever bulk disk you have, import 1,000 files as a trial, and spend an evening with the duplicate filter and the tag search before importing the rest. Leave the PTR off. Turn on the Client API and add Hydrus Companion so web finds go straight in. Back up the database directory to a second disk before every update. If after that trial the interface still feels like a wall, it is not going to click later; move the collection to Immich and keep hydrus for the web-scraped archive only, which is what most people who stay with it end up doing.