Skip to main content

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.

MetadataImmich writes to XMPImmich reads from XMP
Descriptiondc:description, tiff:ImageDescriptiondc:description, tiff:ImageDescription
Ratingxmp:Ratingxmp:Rating
DateTimeexif:DateTimeOriginal, photoshop:DateCreatedIn prioritized order:
exif:SubSecDateTimeOriginal
exif:DateTimeOriginal
xmp:SubSecCreateDate
xmp:CreateDate
xmp:CreationDate
xmp:MediaCreateDate
xmp:SubSecMediaCreateDate
xmp:DateTimeCreated
Locationexif:GPSLatitude, exif:GPSLongitudeexif:GPSLatitude, exif:GPSLongitude
TagsdigiKam:TagsListIn 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:

JobWhat it does
DISCOVERFinds new .xmp files next to media that don’t already have one linked
SYNCRe-reads existing .xmp files and refreshes metadata in the database (e.g. after external edits)

Sidecar Admin Jobs