This is the tagpix user guide. It includes an overview, usage instructions, and version changes. Because tagpix renames and moves photos, users are encouraged to read this guide before running tagpix on valued photo collections. For this program's license, see its main script.
This is an online-only version of this document. It has the same content as the original desktop version shipped in the program's download package, but has been styled for viewing on both desktop and mobile devices. To use this instead of the original version, use your browser to save this page's HTML in the install folder.
If your digital photo collection has become scattered over many folders; uses filenames that are not unique because of their origin on multiple cameras; hosts modification dates that reflect retouches instead of events; or contains arbitrary duplicates, tagpix may be the photo-organizing tool you've been looking for. Running it on your photo folders transforms them into a simple, uniform format that's ideal for both viewing and archiving, and as private as the device on which it is stored.
tagpix moves all the photo files in an entire folder tree to a single folder, adding date taken (or modified) to the front of filenames to make them unique and sortable; discarding any truly duplicate content and adding a unique serial number to the end of any remaining duplicate filenames; isolating movies and other non-image files in folders of their own; and optionally grouping all the merged items into by-year subfolders on request.
The net effect is useful for organizing the contents of disparate photo collections holding pictures and movies shot on multiple cameras over many years. By running tagpix, all the items of each media type are merged on your local computer into a single flat folder, or a set of flat by-year subfolders, for fast, convenient, and private access.
In more detail, here are the main assets that tagpix brings to your photo-normalization jobs:
In addition, tagpix strips prior runs' date prefixes so you can rerun it any number of times on prior results; comes with a list-only mode that allows you to preview its intentions without making any changes; and generates a report that describes all the updates it performs and any files it skips. Read on to learn how to use tagpix to organize your photos.
This section describes tagpix install requirements, inputs and results, usage modes, and other operational details.
tagpix is a single-file program that runs on all major platforms, and is provided in source-code form. It requires installs of either a Python 3.X or 2.X to run its source code, plus the third-party Pillow (a.k.a. PIL) image library for the installed Python to access photo tags. Fetch and install these items if needed from the following sites, respectively (or search the web for other links):
For pointers on Pillow installs, see this page. A note for developers: the exif.py tags-processing alternative to Pillow failed for some files when tested in 2013 for tagpix version 1.0, though your results may vary.
To launch, run script tagpix.py with no command-line arguments. It can be run from a console (e.g., Terminal on Unix and Command Prompt on Windows) and most Python IDEs (e.g., PyEdit and IDLE), though IDEs may not support report routing described ahead.
All run parameters are requested by the following prompts at the program's console:
tagpix renames and moves photos to a merged folder; proceed?
Source - pathname of folder with photos to be moved?
Destination - pathname of folder to move items to?
Group items into by-year subfolders?
List only: show new names, but do not rename or move?
Delete all prior-run outputs in "<output folder name>"?
For all prompts except #2 and #3, type "y" for yes, and type "n" or simply press Enter (return) for no.
To end the script immediately without making any changes, reply no to prompt #1, or enter control+C (or kill the program) at any other prompt. List-only mode (replying yes to #5) analyzes content and shows planned changes but does not perform them; use this to preview and verify the script's updates. Prompt #6 is important when rerunning tagpix; see ahead for its roles.
In all usage modes, the paths you input at prompts #2 and #3 can be either relative to your current location in a console (e.g., "." for the current folder), or absolute (e.g., "/Users/you/photos" on Unix, "C:\My-Photos\unmerged on Windows). For instance, when running tagpix via command lines, you can "cd" to the folder containing your MERGED destination folder and/or source folder, and give folder paths relative to where you are working. Absolute paths are generally required when running tagpix from an IDE such as PyEdit. As usual, the tagpix.py script's path in command lines can be relative or absolute too.
This script's initial prompts are printed to the stderr stream, and its report is printed to stdout. Both go to the console by default, but this two-stream model allows you to save the tagpix report to a file for later inspection—especially handy for larger runs. To start tagpix and save just its report to a file, use a console command line like this to route stdout to a file (">" shell syntax will not work when running tagpix from most IDEs):
python tagpix.py > report.txt
Any special message lines in the report all begin with "***"; search for this in the saved report text after a tagpix run.
For a sample of report content, see the demo logs in the example runs folder; report text is all that following the last input prompt. For a comprehensive report example from a tagpix run on a very large photo collection, including duplicates, locked-file errors, prior-run dates, and more, see this file.
The script's results show up in the "MERGED" folder nested in the destination folder (prompt #3), split into "PHOTOS," "MOVIES," and "OTHERS" subfolders that each contain merged and uniquely named content files. If you reply yes to prompt #4, these three subfolders further group their content into year subfolders. Specifically, the results are organized into a shallow tree as follows:
Destination or ./ MERGED/ PHOTOS/ flat content, or year subfolders with flat content MOVIES/ flat content, or year subfolders with flat content OTHERS/ flat content, or year subfolders with flat content
As described earlier, all filenames at the bottom levels of the results tree include date prefixes added to make them unique (e.g., "2017-10-14__file.jpg"). The dates added reflect either date-taken tag values (for most shot photos), or date-modified file attributes (for all others).
For photo files, date taken is always used if present, because it both ensures that names are unique (different cameras may reuse the same names), and reflects the recorded event's date (date modified may instead be a latest-retouch date after edits, but a date-taken tag is likely to survive). Although date taken may not apply to photo scans, for most photos shot on digital cameras the expanded names chronologically identify both the photos themselves and the scenes they capture.
Items not recognized as movies or tagged photos are moved to OTHERS. After a tagpix run, you may wish to manually remove items from OTHERS that reflect camera-specific cruft. For example, some cameras create ".THM" or ".CTG" files which are irrelevant to your content in PHOTOS and MOVIES. tagpix does not omit these automatically, because it prefers to err on the side of caution (only well-known ".*" hidden files are skipped). Be sure to delete only cruft: OTHERS may contain PNGs and GIFs too.
For a more graphical look at results trees, see the examples folder's screenshots of both flat and group-by-year modes.
Following a run, you should check the report's final "Missed" section to see if any files were skipped due to:
All items skipped are left intact in the source tree, and listed in the "Missed" section.
If the "Missed" line shows "0" skips, or if you are okay with the items skipped, delete the contents of your source folder after the run if desired; if there were no skips, it's just empty directories.
If the "Missed" line's skips is not "0" and valid items were skipped, resolve their issues (e.g., fix locks or permissions, or use a shorter destination path on Windows) and rerun tagpix to transfer them; use your same source and destination folders, and do not delete the prior run's results (for prompts #2, #3, and #6).
Depending on the replies you provide to input prompts, you can use this script to either extend an existing archive or make one anew, and can do both with the aid of another program:
For an example of usage mode A, see the examples here and here. For additional usage-mode examples, see the full examples folder.
This section collects smaller usage notes and tips. Some summarize earlier coverage.
tagpix has been tested extensively and used successfully on extremely large photo collections, and will likely perform well on yours too. It's provided freely because it can help you simplify your photo libraries. Especially given the many ways that computers can fail, however, a word of caution is in order.
By design, this script renames all photos and other files in an entire source folder tree, and moves them to destination folders. No automated method for undoing the changes it makes is provided, and no warranty is included with this program. Please read all usage details here carefully before running tagpix on your photos. Its list-only mode can be used to view but not apply changes, and it is recommended to run tagpix on a temporary copy of your folder tree.
Lest that sound too dire, keep in mind that errors simply leave items in their original location, and a rerun can propagate them to the destination. Still, the importance of your photos merits a complete understanding of any tool that modifies them—this one included.
This section tersely describes changes made in the most recent release—version 2.0, released October 17, 2017 (and republished January 12, 2018 with only minor user-guide and example changes). It is primarily meant for developers and prior-version users. No new usage-level details are introduced in this section, though it may serve as additional context.