TagStudio: a tag-based library layer for your existing photo and file folders

The problem TagStudio is aimed at: tags without a new filesystem

Most photo organizers ask you to import. You point them at a folder, they copy or move files into a managed library, and from then on the application owns the arrangement. TagStudio takes the opposite position. The README describes libraries as acting "as a layer on top of your existing folders and file structure," and states that creating a library does not move files. The comparison the project itself draws is to Obsidian vaults.

The audience follows from that. If you have a directory tree you have maintained for years, with naming conventions and folder groupings that mean something to you, TagStudio is designed to sit beside it. You get tags, fields, and search without renaming anything. The cost is that TagStudio is not the source of truth for where a file lives. Move a file outside the application and the library has to catch up.

All file types are supported in libraries, but preview support is narrower. The README says previews cover raster images, vector SVG, animated formats, RAW, video, plaintext, and documents, eBooks, PSDs, Blender and Krita projects "if supported," and it points to a Supported Previews page for the full list. That distinction matters: a library can index a file it cannot show you.

How the library, entries and SQLite database fit together

When you open a folder as a library, TagStudio places a `.TagStudio` folder inside it. That folder holds a SQLite database containing the tags, the fields, and the records for every file, which the project calls "entries." The files themselves stay where they are. Nothing is duplicated.

Tags are not strings. Each tag carries a name, a shorthand name, aliases, a color, parent tags, and an "Is Category" flag. The name does not have to be unique, which is why parent tags can be marked for disambiguation: the README's example is a "Freddy Fazbear" tag with "Five Nights at Freddy's" as a parent, displayed as "Freddy Fazbear (Five Nights at Freddy's)," or shortened to the parent's shorthand if one exists. Parent tags also work as search substitutions, so a query for a parent matches children.

Fields are the second metadata layer, attached to entries rather than tags. The README lists hardcoded field names such as Title, Author, and Series, with custom field names described as planned for an upcoming update. Field types are text lines, text boxes, and datetimes. That is a small vocabulary, and it is the clearest sign that the data model is still moving.

Search syntax: path, filetype, mediatype and boolean groups

Search is where the tag model pays off. The README documents queries against tags, file paths with `path:`, file types with `filetype:`, and media types with `mediatype:`. Boolean operators AND, OR, and NOT combine with parentheses, quotation escaping, and underscore substitution.

Path matching uses glob syntax, and the README is explicit that you may need to wrap a filename or filepath in asterisks while searching, adding that this will not be strictly necessary in future versions. That is a rough edge worth knowing before you conclude a search is broken.

Two special conditions exist: `special:untagged` and `special:empty`, which find entries with no tags and no fields respectively. These are the queries that make a tag system honest, because they surface the part of the archive you have not processed yet.

Installing TagStudio and opening your first library

The README's Installation section is not reproduced in full here, and the project directs readers to docs.tagstud.io for it. What the repository does give is packaging metadata: the project is named TagStudio, version 9.6.4 in `pyproject.toml`, licensed GPL-3.0-only, and it requires Python `>=3.14,<3.15`. The GUI entry point is declared as `tagstudio` mapping to `tagstudio.__main__:main`, so an installed environment exposes a `tagstudio` command.

The dependency list is long and includes PySide6, SQLAlchemy, Pillow, opencv_python, rawpy, ffmpeg-python, mutagen, py7zr, and rarfile. Several of those are compiled or bind to native libraries, so a source install is not a single trivial step.

python3.14 -m venv .venv
source .venv/bin/activate
pip install .
tagstudio

Running `tagstudio` should open the application. From the menu bar, File -> Open/Create Library lets you choose a directory; TagStudio creates a library there if one does not exist and scans the folders for files. The README states plainly that no files are moved during that process. You should see entries appear for the files in the directory you chose.

Once a library is open, refreshing is the operation you will use most. Libraries under 10,000 files scan automatically when opened. For anything else, use File -> Refresh Directories, or the shortcut:

# macOS: Command+R
# Windows and Linux: Ctrl+R

The README's Basic Usage section covers creating a library, refreshing, and creating tags, and then points to docs.tagstud.io/libraries for the rest. If you are evaluating TagStudio, the documentation site is the real manual; the README is a front door.

Where TagStudio gets awkward: scale, alpha releases and refresh behaviour

The 10,000-file threshold is the most concrete limitation in the README. Below it, opening a library triggers a scan for new or modified files. Above it, that automatic scan does not happen, and you are expected to refresh manually. For a photo archive of any size, that means the application's freshness depends on you remembering a keystroke.

The release history reinforces the point. The most recent releases are v9.6.3, v9.6.2, and v9.6.1, all labelled Alpha. The README screenshot is captioned as Alpha v9.5.5. This is software that tells you what it is.

There is a second failure mode implied by the architecture. Because the library is a layer and files are not moved, the database and the filesystem can diverge. Delete or rename a file in your file manager and the entry in the SQLite database is not automatically the truth. The README does not document how reconciliation works in that case, and it does not document rollback. That silence is worth weighing if you plan to run TagStudio against an archive you cannot afford to re-index.

Finally, custom field names are planned, not present. If your metadata model needs fields beyond Title, Author, Series and the other hardcoded names, TagStudio is not there yet.

TagStudio versus TagSpaces: database layer or filename-embedded tags

TagSpaces is the natural comparison, and the two projects make opposite bets. TagSpaces writes tags into the filename or into sidecar files, so the tagging survives even if the application disappears. TagStudio keeps tags in a SQLite database inside a `.TagStudio` folder and leaves filenames untouched.

The README frames this as a deliberate choice: "no sea of sidecar files, and no complete upheaval of your filesystem structure." The benefit is clean filenames and a structured tag model with parents, aliases and colors that a filename cannot express. The cost is that your metadata lives in a binary database tied to one application. Backing up the `.TagStudio` folder becomes part of backing up the library.

Neither approach is universally better. If portability of tags across tools is your priority, filename-embedded tagging wins. If you want a richer tag graph and are comfortable treating the database as a first-class artifact, TagStudio's model is the more expressive one.

Licence, maintenance and what upgrading actually involves

TagStudio is GPL-3.0-only, stated in both the README's SPDX header and `pyproject.toml`. The repository also carries a REUSE.toml and a LICENSES directory, and the README shows a REUSE compliance badge, so the project tracks per-file licensing. For most users this changes nothing; if you intend to redistribute TagStudio or build on its source, the copyleft terms apply and are worth reading in full rather than taking from a summary. This is not legal advice.

Maintenance is active: the last push to the main branch was on 2026-09-16, and the 9.6.x alpha releases arrived in July and August 2026. The version in `pyproject.toml` is 9.6.4, ahead of the latest tagged release, which is normal for a project that bumps versions on the main branch.

The upgrade cost is the part to think about. The project pins `requires-python = ">=3.14,<3.15"`, an unusually narrow window, and pins PySide6 to exactly 6.11.2. An upgrade that moves the Python requirement will force you to rebuild your environment. Because library data lives in a SQLite database whose schema is not documented in the README, you should copy the `.TagStudio` folder before upgrading across minor versions. The README does not document a migration or rollback path.

Editorial conclusion

TagStudio fits people who already have a folder structure they like and want searchable, structured metadata on top of it without sidecar files or a database that owns their media. It does not fit anyone who needs a stable, feature-frozen organizer today: the releases are alpha builds, the README itself points to the documentation site for anything beyond basic usage, and custom field names are described as planned rather than present. Before committing a large archive, verify that your Python version satisfies the >=3.14,<3.15 requirement, that your file types appear on the supported previews page, and that your library size is one you are willing to refresh with Ctrl+R rather than relying on the automatic scan.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. TagStudioDev/TagStudio on GitHub