From 7e6cd48783092656d1859c1bb11e40e958611fca Mon Sep 17 00:00:00 2001 From: trommegutten Date: Thu, 11 Sep 2025 16:00:53 +0200 Subject: [PATCH] docs: improve and clarify XMP sidecar behavior (#20334) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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() --- docs/docs/features/img/xmp-sidecars.webp | Bin 11118 -> 0 bytes docs/docs/features/xmp-sidecars.md | 67 +++++++++++++++++++++-- 2 files changed, 61 insertions(+), 6 deletions(-) delete mode 100644 docs/docs/features/img/xmp-sidecars.webp diff --git a/docs/docs/features/img/xmp-sidecars.webp b/docs/docs/features/img/xmp-sidecars.webp deleted file mode 100644 index f00b32c730145bb14d391a3504e9517b09d321b6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11118 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 +:::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. +::: -XMP sidecars are external XML files that contain metadata related to media files. Many applications read and write these files either exclusively or in addition to the metadata written to image files. They can be a powerful tool for editing and storing metadata of a media file without modifying the media file itself. When Immich receives or detects an XMP sidecar for a media file, it will attempt to extract the metadata from both the sidecar as well as the media file. It will prioritize the metadata for fields in the sidecar but will fall back and use the metadata in the media file if necessary. +## Metadata Fields -When importing files via the CLI bulk uploader or parsing photo metadata for external libraries, Immich will automatically detect XMP sidecar files as files that exist next to the original media file. Immich will look files that have the same name as the photo, but with the `.xmp` file extension. The same name can either include the photo's file extension or without the photo's file extension. For example, for a photo named `PXL_20230401_203352928.MP.jpg`, Immich will look for an XMP file named either `PXL_20230401_203352928.MP.jpg.xmp` or `PXL_20230401_203352928.MP.xmp`. If both `PXL_20230401_203352928.MP.jpg.xmp` and `PXL_20230401_203352928.MP.xmp` are present, Immich will prefer `PXL_20230401_203352928.MP.jpg.xmp`. +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. -There are 2 administrator jobs associated with sidecar files: `SYNC` and `DISCOVER`. The sync job will re-scan all media with existing sidecar files and queue them for a metadata refresh. This is a great use case when third-party applications are used to modify the metadata of media. The discover job will attempt to scan the filesystem for new sidecar files for all media that does not currently have a sidecar file associated with it. +:::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//YYYY/YYYY-MM-DD/IMG_0001.jpg` + `upload/library//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](https://github.com/immich-app/immich/issues/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](./img/sidecar-jobs.webp)