Installation¶
photo-tagger is a Python 3.14+ command-line tool. Install it once with your tool manager of choice,
make sure ExifTool is on your PATH, and you are ready to start tagging photos.
End-user install¶
Install photo-tagger with the tool manager you prefer. uv and
pixi are the recommended options: each puts the photo-tagger command on your
PATH in its own isolated environment.
Note
New releases land on PyPI (uv, pipx) first; the conda-forge packages (conda, pixi) usually follow within a day. If a fresh version is not on conda-forge yet, that lag is why.
The conda-forge packages (conda, pixi) also pull in ExifTool for you, so you can skip the
manual ExifTool install. The PyPI installs (uv, pipx) cannot, since pip has
no way to ship the non-Python exiftool binary, so install it separately.
Upgrade to the latest release the same way:
pixi installs the conda-forge package as a global tool:
Upgrade to the latest release with:
The package is published on conda-forge, so it also installs with conda (or mamba):
If you already use pipx, install from PyPI with:
Optional desktop GUI¶
photo-tagger ships an optional desktop GUI behind the gui extra. It is kept out
of the base install so the plain CLI stays lightweight (no Qt dependency). On PyPI the extra pulls
in PySide6; on conda-forge the GUI is a separate package, photo-tagger-gui, that bundles PySide6
for you.
Then launch it with photo-tagger gui. Everything else on this page applies unchanged; the GUI uses
the same ExifTool, model server, and configuration as the CLI.
From source¶
To work on photo-tagger itself, clone the repository and let uv create the development environment.
The dev and test dependency groups pull in the linters, type checker, and test runner.
git clone https://github.com/jbsilva/photo-tagger.git
cd photo-tagger
uv sync --group dev --group test
See the Development section for the full workflow, including the local checks to run before committing.
Tip
The repository ships a dev container (.devcontainer/devcontainer.json) for a zero-setup
environment: open the project in a container and it installs uv, ExifTool, the dependency groups,
and the git hooks for you. See Development for details.
System requirements¶
photo-tagger needs Python 3.14 or newer plus two external libraries that are not Python packages.
ExifTool does the actual metadata reading and writing; photo-tagger drives
the exiftool binary through pyexiftool. The conda-forge packages (conda, pixi) already pull it in
as a dependency, so this step is only needed for the PyPI installs (uv, pipx). Install it with your
system package manager:
Download a build for your platform from exiftool.org.
On macOS, RAW decoding through rawpy needs libraw as well. Install it with Homebrew:
On Linux the rawpy wheels bundle libraw, so no extra step is needed there.
Warning
The exiftool binary must be on your PATH. photo-tagger shells out to it for every photo, so if
it is not found the run will fail. After installing, confirm it is visible with exiftool -ver (see
Verify below).
Verify¶
Check that the command and its ExifTool dependency are both reachable:
The first prints the CLI options; the second prints the installed ExifTool version. Once both work, head to Configuration to point photo-tagger at your model server. If either command fails, or your first run will not start, see Troubleshooting for the most common causes and fixes.