Hydrus Network: a tagger for 10,000-file collections

What Hydrus Network solves, and who it is actually for

Folders scale badly. Once a collection passes a few thousand files, the directory tree stops being a description of the content and becomes a description of when you downloaded it. Hydrus Network takes the other position: a file lives in one place on disk, and everything you know about it lives in tags. The README describes the client as a file-management application written for internet-fluent media nerds who have large file collections, and says it browses with tags instead of folders, a little like a booru on your desktop.

The stated audience is narrow and the README admits it. If you have 10,000+ files and cannot find anything, hydrus might help. That threshold matters. Below it, a well-named folder tree and a desktop search tool are cheaper. Above it, the tag model starts paying for itself, because a single file can carry a character tag, a source tag, a rating and a series tag at once, and any of those can be the entry point.

The second audience is people who want their metadata to outlive any single website. The client can import files and tags from your hard drive and from popular websites, and the README says users can easily share tags anonymously through a public server. That is the network half of the name: the media stays local, the tags can travel.

How the client, the server, and the downloaders fit together

There are two executables in the repository root. hydrus_client.py starts the desktop application, and hydrus_server.py starts the server that other users can connect to. They are separate processes with separate responsibilities, and the README treats the server as optional infrastructure rather than a required backend. Nothing in your client depends on someone else's server being up.

The import path is where most of the work happens. The client reads files from your hard drive and parses tags and other metadata from simple websites using user-made downloaders, which the README describes as easily shareable. A downloader is a configuration artifact, not a plugin in the compiled sense: you can pass one to another user, and the repository links to a user-run collection of presets and scripts. That design is why the project can support many sites without shipping code for each one.

The repeating behaviour is the subscription system. The README states the client can be set to subscribe to any gallery search, repeating it every few days to keep up with new results. So the data flow is: a search URL plus a downloader produce files and tags, the subscription re-runs that search on a schedule, and new results land in your local database already tagged. The client also never phones home according to the README, which means the only outbound traffic is what you configure.

On playback, the README gives two options: an mpv embed or a native Qt player. Some supported filetypes cannot be viewed in the client at all, PDF being the named example, and those open through your operating system's default program instead.

Installing Hydrus Network and running a first import

The README points to executable releases for Windows and Linux, and says the program is in python, so you can also run it straight from the source code in Windows, Linux, or macOS. If you go the source route, pyproject.toml documents both package managers at the top of the file. This is the pip path:

pip install .

For uv, the same file says to just do the normal sync, which installs the pinned dependency set:

uv sync

The interpreter range is declared in pyproject.toml as requires-python = ">=3.10,<3.15". Check that before anything else, because a system Python outside that window will fail at resolution rather than at runtime, and the failure message will not mention Hydrus.

Once dependencies are in place, the client entry point is a script in the repository root:

python hydrus_client.py

The README says the help is included in every release and that you should not skip it, and this is the point where that advice bites. The first run creates your database and asks you to set up a file import. The Getting Started Guide walks through installation and the main systems of the program, and the README explicitly warns that Hydrus can do a lot, so while you can skim the help, do not skip it. For a first real use, import a folder you already know well. If the tags you apply there feel natural, the model fits your collection. If you find yourself recreating your folder names as tags, it does not.

Where Hydrus Network is the wrong tool

The README is unusually direct about this: it is quite an advanced program, and not a beautiful one, so it isn't for everyone. That is not modesty, it is a description of the interface. If your standard for a media manager is a gallery app that looks right on first launch, Hydrus will read as hostile, and the tag vocabulary you have to build before search becomes useful is real unpaid labour.

The sharing model has a sharper limitation. Tags can be shared through user-run servers, and the README frames that as anonymous and optional. But the media does not travel with them by default, and there is no central index that guarantees a tag means the same thing in two repositories. Two servers can use the same tag name for different things, and nothing in the protocol resolves that for you. If you need a shared, authoritative catalogue, this is not it.

Support expectations are another boundary. The README states the author is not active on GitHub and welcomes feedback on other channels, aiming to get back to pings every Saturday. Public pull requests are currently closed, though the issue tracker is active and run by volunteer users. So you get a weekly release cadence and a community-run tracker, not a vendor relationship. If your organisation needs a support contract or a merge path for your own patches, Hydrus is the wrong shape. Forking is explicitly permitted, but that means you own the divergence.

Hydrus Network compared with a self-hosted gallery server

The obvious alternative for a large local collection is a self-hosted web gallery, the kind you run on a home server and open in a browser. The difference is where the database lives and who it serves. A gallery server is built around serving files outward: it indexes a directory, generates thumbnails, and exposes a web interface to whoever can reach the port. Hydrus is built around a single user's local database, with the server as a separate optional component for tag sharing rather than for browsing your collection from another device.

That changes the failure modes. A web gallery degrades gracefully when its index is lost, because the files and their folder structure are still the source of truth. Hydrus inverts this: the tags are the source of truth, so the database is the asset, and the README's emphasis on you controlling everything cuts both ways. You control the backups too.

A second alternative is doing nothing, and letting your operating system's search handle it. That works while filenames carry the information. It stops working when the information is relational, when you want every file by one artist that also carries a specific character tag, and no filename convention survives that. The crossover point the README names, 10,000+ files, is roughly where filename search stops answering questions.

Maintenance, release cadence, and the licence question

The release cadence is stated plainly: the author tries to put out a new release every Wednesday by 8pm EST. The recent tags back that up, with v685, v686 and v687 landing on consecutive Wednesdays in 2026. The last push to the default branch was on 2026-09-23, so the repository is current. Version numbers in pyproject.toml track the release tag, which means an upgrade is a version bump plus whatever database migration the client performs on first launch.

The upgrade cost is mostly in the database, not the code. Because tags are the primary data, a migration that goes wrong is not recoverable by re-scanning a folder. The README does not document rollback, and no downgrade path is described in the project's help or repository files. Treat a client backup before each version jump as part of the routine, not an optional precaution.

On licensing, the repository's LICENSE file is present but the metadata reports NOASSERTION, meaning the licence could not be classified automatically. The README's own words are that you should feel free to fork and do whatever you like with my code, while public pull requests are currently closed. Those two statements are about different things: forking is a licence question, and contributing is a project policy question. Read the LICENSE file itself rather than the metadata field, and do not treat the README sentence as a substitute for it. Nothing here is legal advice.

Editorial conclusion

Adopt Hydrus if your collection has outgrown folders and you accept a tag-first workflow plus a client that stores everything locally. Do not adopt it if you want a hosted service, a polished consumer interface, or a project that takes public pull requests, because the README states those are currently closed. Before committing, verify that your Python falls inside the pyproject.toml range of >=3.10,<3.15, that your media types appear in the supported filetypes list, and that the Getting Started Guide's install path matches your operating system.

Frequently asked questions

Official sources

1. hydrusnetwork/hydrus on GitHub
2. Issues
3. Project website
4. README
5. Releases