DeepDanbooru: training a multi-label tag estimator on your own Danbooru-format dataset

The problem: tag strings that only exist as free text

Danbooru-style datasets store labels as a single space-separated string in a tag_string column, for example 1girl ahoge long_hair. That is convenient for a website and awkward for a classifier, which needs a fixed vocabulary and a per-tag binary target. DeepDanbooru exists to close that gap. It reads the SQLite posts table, takes tags.txt as the authoritative label set, and trains a model that outputs a score per tag rather than a single class. The intended user is someone who already has, or can download with DanbooruDownloader, a corpus in that exact shape and wants a model tuned to their own tag list. The README's own framing is narrower than the repository topics suggest: it calls the project an anime-style girl image tag estimation system. If your images are not in that domain, the published checkpoint is unlikely to be useful to you, and you are back to training from scratch.

How the training pipeline is wired together

A project folder is the unit of work, and it holds only two files: project.json and tags.txt. The tag list is a newline-separated file, one tag per line, and it can be hand-written or fetched from the Danbooru server with an account and API key. The dataset is a SQLite file placed beside an images folder. Images live in subfolders named after the first two characters of the filename, and each file must be named [md5].[file_ext]. The README states that md5 does not have to be a real MD5 hash, which means the naming scheme is really just a two-level bucketing convention to avoid huge flat directories. The posts table needs five columns: id, md5, file_ext, tag_string, and tag_count_general. That last column drives the minimum_tag_count project setting, and images whose tag_count_general is below the threshold are not used for training. This is the one place where the data contract has teeth. A sparse post with three tags disappears from training without an error, and the only signal is a smaller effective dataset.

Installing it and running the four commands that matter

The package requires Python 3.11 and lists Click, numpy, requests, scikit-image, six, tensorflow and tensorflow-io as dependencies. Two install paths are documented. The first is pip install -r requirements.txt. The second is a package install where tensorflow is deliberately excluded by default: pip install . gives you the CLI without the framework, and pip install .[tensorflow] adds it. That split matters on machines where TensorFlow is already managed separately, and it also means a plain pip install . followed by a training run will fail at import time rather than at install time. The workflow is then four commands. deepdanbooru create-project [your_project_folder] scaffolds the project. deepdanbooru download-tags [your_project_folder] --username [account] --api-key [key] pulls the current tag list from Danbooru. deepdanbooru make-training-database [dataset_sqlite_path] [filtered_sqlite_path] optionally converts rating and score into system tags for filtering. deepdanbooru train-project [your_project_folder] starts training, and deepdanbooru evaluate [image_file_path or folder]... --project-path [your_project_folder] --allow-folder runs inference. The --allow-folder flag is required when the argument is a directory rather than a file, which is easy to miss on a first attempt.

The step the README buries: editing project.json

Between creating the project and training it, step 5 says to modify project.json in the project folder and change database_path to the actual SQLite file path. This is the only configuration edit the README describes, and it is the most common place for a first run to go wrong, because create-project cannot know where your database lives. The documentation does not enumerate the other keys in project.json, including minimum_tag_count, even though the dataset section explains what that setting does. Anyone training on a filtered database produced by make-training-database should expect to reconcile the two by hand: the filtered file is a new path, and project.json still points at the old one until you change it. Treat project.json as the real interface of the project and read it after create-project rather than assuming the README lists every field you may need to touch.

Where it stops being the right tool

Three limits are visible in the material. First, the tag vocabulary is whatever is in tags.txt. A pretrained checkpoint is bound to the tag list it was trained against, so swapping in a custom tags.txt without retraining produces a model whose output rows no longer correspond to your labels. Second, download-tags requires a Danbooru account and API key, so the convenient path to a current vocabulary depends on a third-party service being reachable and on you holding credentials. Third, the input contract is rigid: a SQLite posts table with the listed columns, images bucketed by the first two filename characters, and filenames of the form [md5].[file_ext]. If your corpus is a directory of JPEGs with a CSV of labels, you are writing a conversion script before you can run a single training step. There is also no inference server, no REST endpoint, and no GUI in the repository as described; evaluate is a command-line entry point, and the web demo is a separate hosted page, not something you deploy from this code.

Compared with a general-purpose vision tagging model

The obvious alternative is a general image tagging model trained on broad photographic data. The difference is the label space, not the architecture. A general tagger emits everyday object and scene categories and has no notion of the tag_string vocabulary that Danbooru uses, so its output cannot be compared against a Danbooru post without a mapping layer that you would have to build and maintain. DeepDanbooru takes the opposite approach: it treats your tags.txt as the definition of the problem and learns exactly those labels, which is why it needs a training run rather than a single inference call. The trade is effort for alignment. You spend a dataset conversion and a training job to get outputs that land directly in the same vocabulary as your existing posts. If your goal is rough descriptive keywords on arbitrary images, the general model is the shorter path. If your goal is to reproduce or extend the labels already attached to a Danbooru-format corpus, the general model is the wrong shape of output entirely.

Maintenance, releases and the MIT licence

The repository is not archived and the last push is dated 2026-07-04. Releases are pretrained model checkpoints rather than library versions: v3-20211112-sgd-e28 from February 2022, v4-20200814-sgd-e30 from September 2020, and v3-20200915-sgd-e30 from November 2020. The naming encodes a version, a date and a training schedule detail, which tells you a checkpoint is a frozen artifact you select rather than a dependency you upgrade in place. Upgrading the library does not upgrade the model. The dependency list is the real maintenance surface: tensorflow>=2.17.0 and tensorflow-io>=0.31.0 pin you to the TensorFlow release cadence, and a Python 3.11 requirement constrains the interpreter on the training host. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; this is a statement about the repository's licence file, not legal advice, and you should confirm the terms against the LICENSE in the tree and against the licence of any dataset you train on, which is a separate question the MIT licence does not answer.

Editorial conclusion

Adopt DeepDanbooru if you already hold images in Danbooru's post format and want a tag estimator you can retrain against your own tag list, since the pretrained v3-20211112-sgd-e28 checkpoint only covers the tags in its own tags.txt. Do not adopt it if you need a hosted API, a GUI, or a model that generalizes to photographs, since the README frames it as anime-style girl image tag estimation and nothing in the material suggests otherwise. Before committing, verify three things: that your SQLite file has the posts table columns id, md5, file_ext, tag_string, tag_count_general; that your images sit under images/ in two-character subfolders named [md5].[file_ext]; and that minimum_tag_count in project.json matches what tag_count_general actually contains in your data, because images below that threshold are silently excluded from training.

Official sources

1. Issues
2. KichangKim/DeepDanbooru on GitHub
3. License: MIT
4. README
5. Releases