A User-Focused Photo & File Management System
[!CAUTION] This is still a very rough personal project of mine in its infancy. I’m open-sourcing it now in order to accept contributors sooner and to better facilitate the direction of the project from an earlier stage. There are bugs, and there will very likely be breaking changes!
TagStudio is a photo & file organization application with an underlying system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
filename: <query>
)untagged
/no tags
and empty
/no fields
.[!NOTE] For more information on the project itself, please see the FAQ section as well as the documentation.
If you're interested in contributing to TagStudio, please take a look at the contribution guidelines for how to get started!
To download TagStudio, visit the Releases section of the GitHub repository and download the latest release for your system under the "Assets" section. TagStudio is available for Windows, macOS (Apple Silicon & Intel), and Linux. Windows and Linux builds are also available in portable versions if you want a more self-contained executable to move around.
[!IMPORTANT] On macOS, you may be met with a message saying ""TagStudio" can't be opened because Apple cannot check it for malicious software." If you encounter this, then you'll need to go to the "Settings" app, navigate to "Privacy & Security", and scroll down to a section that says ""TagStudio" was blocked from use because it is not from an identified developer." Click the "Open Anyway" button to allow TagStudio to run. You should only have to do this once after downloading the application.
Optional arguments to pass to the program.
--open <path>
/-o <path>
Path to a TagStudio Library folder to open on start.
--config-file <path>
/-c <path>
Path to the TagStudio config file to load.
With TagStudio opened, start by creating a new library or opening an existing one using File -> Open/Create Library from the menu bar. TagStudio will automatically create a new library from the chosen directory if one does not already exist. Upon creating a new library, TagStudio will automatically scan your folders for files and add those to your library (no files are moved during this process!).
In order to scan for new files or file changes, you’ll need to manually go to File -> Refresh Directories.
[!NOTE] In the future, library refreshing will also be automatically done in the background, or additionally on app startup.
To add a metadata field to a file entry, start by clicking the “Add Field” button under the file preview in the right-hand preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry.
Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup.
Click the “+” button at the end of the Tags list, and search for tags to add inside the new dialog popup. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the add the first item in the list. Press Enter/Return once more to close the dialog box
[!WARNING] Keyboard control and navigation is currently very buggy, but will be improved in future versions.
To create a new tag, click on Edit -> New Tag from the menu bar. From there, enter a tag name, shorthand name, any tag aliases separated by newlines, any subtags, and an optional color.
To edit a tag, right-click the tag in the tag field of the preview pane and select “Edit Tag”
Inevitably, some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red tag with a cross through it (this icon is also used for items with broken thumbnails). To relink moved files or delete these entries, go to Tools -> Manage Unlinked Entries. Click the “Refresh” button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their metadata entries inside your library.
[!WARNING] There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a top priority for future releases.
[!WARNING] If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are top priorities for future versions.
Libraries are saved upon exiting the program. To manually save, select File -> Save Library from the menu bar. To save a backup of your library, select File -> Save Library Backup from the menu bar.
Load in a .dupeguru file generated by dupeGuru and mirror metadata across entries marked as duplicates. After mirroring, return to dupeGuru to manage deletion of the duplicate files. After deletion, use the “Fix Unlinked Entries” feature in TagStudio to delete the duplicate set of entries for the now-deleted files
[!CAUTION] While this feature is functional, it’s a pretty roundabout process and can be streamlined in the future.
Create an image collage of your photos and videos.
[!CAUTION] Collage sizes and options are hardcoded, and there's no GUI indicating the process of the collage creation.
Apply tags and other metadata automatically depending on certain criteria. Set specific macros to run when the files are added to the library. Part of this includes applying tags automatically based on parent folders.
[!CAUTION] Macro options are hardcoded, and there’s currently no way for the user to interface with this (still incomplete) system at all.
Import JSON sidecar data generated by gallery-dl.
[!CAUTION] This feature is not supported or documented in any official capacity whatsoever. It will likely be rolled-in to a larger and more generalized sidecar importing feature in the future.
See instructions in the "Creating Development Environment" section from the contribution documentation.
As of writing (Alpha v9.3.0) the project is in a useable state, however it lacks proper testing and quality of life features.
[!IMPORTANT] See the Planned Features documentation for the latest feature lists. The lists here are currently being migrated over there with individual pages for larger features.
Of the several features I have planned for the project, these are broken up into “priority” features and “future” features. Priority features were originally intended for the first public release, however are currently absent from the Alpha v9.x.x builds.
I’ve been developing this project over several years in private, and have gone through several major iterations and rewrites in that time. This “major version” is just a number at the end of the day, and if I wanted to I couldn’t released this as “Version 0” or “Version 1.0”, but I’ve decided to stick to my original version numbers to avoid needing to go in and change existing documentation and code comments. Version 10 is intended to include all of the “Priority Features” I’ve outlined in the previous section. I’ve also labeled this version as an Alpha, and will likely reset the numbers when a feature-complete beta is reached.
As of right now, no. However, I did have a CLI version in the recent past before dedicating my efforts to the Qt GUI version. I’ve left in the currently-inoperable CLI code just in case anyone was curious about it. Also yes, it’s just a bunch of glorified print statements (the outlook for some form of curses on Windows didn’t look great at the time, and I just needed a driver for the newly refactored code...).