helpy4/immich
1
0
Fork 0
mirror of https://github.com/immich-app/immich synced 2025-10-17 18:19:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
immich/docs/docs/features/xmp-sidecars.md
trommegutten 7e6cd48783
docs: improve and clarify XMP sidecar behavior (#20334) 
* docs: improve and clarify XMP sidecar behavior

- Simplified and reorganized the documentation for XMP sidecars
- Clearly separated CLI import vs. external library behavior
- Clarified what metadata fields are stored in the database
- Documented filename rules and storage behavior
- Explained write-back behavior, including permission requirements

* Clarify sidecar write-back behavior for external libraries

Updated documentation to reflect that Immich does not write metadata to sidecar files in external libraries unless the mount is writable.

Mentions silent fail behavior as described in Issue #10538.

* Update xmp-sidecars.md

* Refactor section 1: clarify XMP fields Immich reads and writes

- Rewrote section 1 with a simplified 3-column table: Metadata · Writes to · Reads from
- Corrected date field logic with prioritized read order
- Clarified that Immich only updates fields that have changed
- Removed incorrect mention of dc:title

* docs: clarify tag reading priority (TagsList, HierarchicalSubject, IPTC:Keywords)

Updated the documentation for tag metadata extraction to clarify the prioritized order in which Immich reads tags from imported media:

1. digiKam:TagsList
2. lr:HierarchicalSubject
3. IPTC:Keywords

This reflects the actual logic used in the getTagList()
2025-09-11 14:00:53 +00:00

5.4 KiB
Raw Blame History

XMP Sidecars

Immich supports XMP sidecar files — external .xmp files that store metadata for an image or video in XML format. During the metadata extraction job Immich will read & import metadata from .xmp files, and during the Sidecar Write job it will write metadata back to .xmp.

:::tip Tools like Lightroom, Darktable, digiKam and other applications can also be configured to write changes to .xmp files, in order to avoid modifying the original file. :::

Metadata Fields

Immich does not support all metadata fields. Below is a table showing what fields Immich can read and write. It's important to note that writes do not replace the entire file contents, but are merged together with any existing fields.

:::info Immich automatically queues a Sidecar Write job after editing the description, rating, or updating tags. :::

Metadata Immich writes to XMP Immich reads from XMP
Description dc:description, tiff:ImageDescription dc:description, tiff:ImageDescription
Rating xmp:Rating xmp:Rating
DateTime exif:DateTimeOriginal, photoshop:DateCreated In prioritized order:
exif:SubSecDateTimeOriginal
exif:DateTimeOriginal
xmp:SubSecCreateDate
xmp:CreateDate
xmp:CreationDate
xmp:MediaCreateDate
xmp:SubSecMediaCreateDate
xmp:DateTimeCreated
Location exif:GPSLatitude, exif:GPSLongitude exif:GPSLatitude, exif:GPSLongitude
Tags digiKam:TagsList In prioritized order:
digiKam:TagsList
lr:HierarchicalSubject
IPTC:Keywords

:::note All other fields (e.g. Creator, Source, IPTC, Lightroom edits) remain in the .xmp file and are not searchable in Immich. :::

File Naming Rules

A sidecar must share the base name of the media file:

  • ✅ IMG_0001.jpg.xmp ← preferred
  • ✅ IMG_0001.xmp ← fallback
  • ❌ myphoto_meta.xmp ← not recognized

If both .jpg.xmp and .xmp are present, Immich uses the .jpg.xmp file.

CLI Support

  1. Detect – Immich looks for a .xmp file placed next to each media file during upload.
  2. Copy – Both the media and the sidecar file are copied into Immich’s internal library folder.
    The sidecar is renamed to match the internal filename template, e.g.:
    upload/library/<user>/YYYY/YYYY-MM-DD/IMG_0001.jpg
    upload/library/<user>/YYYY/YYYY-MM-DD/IMG_0001.jpg.xmp
  3. Extract – Selected metadata (title, description, date, rating, tags) is parsed from the sidecar and saved to the database.
  4. Write-back – If you later update tags, rating, or description in the web UI, Immich will update both the database and the copied .xmp file to stay in sync.

External Library (Mounted Folder) Support

  1. Detect – The DISCOVER job automatically associates .xmp files that sit next to existing media files in your mounted folder. No files are moved or renamed.
  2. Extract – Immich reads and saves the same metadata fields from the sidecar to the database.
  3. Write-back – If Immich has write access to the mount, any future metadata edits (e.g., rating or tags) are also written back to the original .xmp file on disk.

:::danger If the mount is read-only, Immich cannot update either the sidecar or the database — metadata edits will silently fail with no warning see issue #10538 for more details. :::

Admin Jobs

Immich provides two admin jobs for managing sidecars:

Job What it does
DISCOVER Finds new .xmp files next to media that don’t already have one linked
SYNC Re-reads existing .xmp files and refreshes metadata in the database (e.g. after external edits)

Sidecar Admin Jobs