ImmichMetaMedic

Mass Check Image and Video files before Uploading them to Immich.
Assumption: Files are organized in a YYYY/MM, YYYY-MM, or YYYY_MM folder structure.

By default, the tool checks each file's best timestamp against the YYYY/MM, YYYY-MM, or YYYY_MM folder it resides in. If a conflict is found, you are prompted for action.

New: You can now use the --year parameter to check all files for conflicts against a specific year, regardless of their folder structure. If --year is provided, the tool ignores the folder year/month and only compares the file's year to the given year.

Note: Sub-second tags only refine their paired base tag and should not be used standalone. Filesystem timestamps are queried as fallback when no embedded metadata exists (used by Immich as last resort).

• DateTimeOriginal (plus SubSecDateTimeOriginal if present)
• XMP:DateTimeOriginal
• CreateDate (plus SubSecCreateDate if present)
• XMP:CreateDate
• QuickTime:CreateDate
• QuickTime:TrackCreateDate
• QuickTime:MediaCreateDate
• MediaCreateDate
• CreationDate
• DateTimeCreated
• FileModifyDate (filesystem modification time, fallback)
• FileCreateDate (filesystem creation time, fallback)

Requirements

• Python 3.10+
• ExifTool installed and available on PATH (https://exiftool.org/)

Install

pip install -e .

Usage

Scan a root folder organized as YYYY/MM, YYYY-MM, or YYYY_MM:

immich-meta-medic C:\path\to\photos

To check all files against a specific year (e.g., 2019):

immich-meta-medic C:\path\to\photos --year 2019

Options:

• --year checks all files for conflicts against the given year, ignoring folder structure.
• --dry-run shows what would be written without modifying files.
• --non-interactive only reports conflicts and never prompts.
• --extensions lets you override the default extension list.

Conflict handling

When a file's best timestamp does not match its YYYY/MM folder, the tool prompts you to:

• Pick any existing timestamp from the file (all options are shown).
• Enter a new timestamp in YYYY:MM:DD HH:MM:SS format (validated).
• Skip the file.

The chosen timestamp is written to all known date tags in the sequence. Sub-second tags are set when fractional seconds are present; otherwise they are cleared to avoid stale values.