My Immich pitfalls

After getting Immich running on Kubernetes, I assumed the hard part was over.

Narrator: It wasn’t.

Most of the issues I encountered weren’t bugs at all – they were simply things that weren’t immediately obvious from the documentation. Hopefully, this article saves you a few hours of trial and error.

The library directory is not an import folder

This was my biggest misunderstanding. After uploading my first image from the mobile app, Immich created the following directory structure:

/data
  backups
  encoded-video
  library
  profile
  thumbs
  upload

I assumed that library was where I should copy my existing photo collection. So I copied a few photos into it.

Narrator: Nothing happened.

Rescanning didn’t help. The reason is simple: the library directory is Immich’s internal storage, not a watched folder. Immich keeps track of every asset inside PostgreSQL. Simply copying files into the storage directory doesn’t create database records, thumbnails or metadata.

If you want to migrate an existing collection, you have three supported options:

• Import the files into Immich.
• Upload the files to Immich.
• Use an External Library.

Don’t manually copy files into library.

External Libraries cannot be placed inside the upload directory

After discovering External Libraries, I thought I’d simply create another folder:

/data
  external-library

Unfortunately, Immich refuses this configuration, trying to register it results in: Cannot use media upload folder for external libraries.

The upload location and external libraries must be separate, so my final layout looks like this:

/data
  library
  upload
  thumbs
  ...
/external-library
  1989
  1990
  1991
  ...

The first location is managed entirely by Immich. The second one contains my existing photo archive, that I uploaded as is.

Google Takeout metadata

My archive partially comes from Google Photos using Google Takeout, each image looks like this:

19940301_27.jpg
19940301_27.jpg.supplemental-metadata.json

Initially I was worried that Immich would ignore the Google metadata, fortunately, most of my photos already contain proper EXIF metadata:

• capture date
• GPS coordinates

Immich reads these directly from the JPEG files, so in my case the Google JSON files turned out to be mostly unnecessary. If your EXIF metadata is missing, however, your migration strategy may need a bit more planning.

Immich writes XMP sidecars

This was probably the nicest surprise, after editing the GPS location of a photo, I noticed that Immich created:

19940301_27.jpg.xmp

The generated file contains standard XMP metadata, for example:

<exif:GPSLatitude>46,4.59558N</exif:GPSLatitude>
<exif:GPSLongitude>18,17.16606E</exif:GPSLongitude>

For someone digitizing old negatives and slides, this is a huge deal, I don’t want my manually corrected dates and GPS locations to live only inside a PostgreSQL database. Having the metadata stored alongside the original image in an open format makes future migrations significantly easier. I still need to investigate exactly which metadata Immich writes to XMP, but this already looks very promising.

PostgreSQL isn’t scary

At first I wasn’t particularly happy that Immich stores so much information in PostgreSQL. After thinking about it, I realized that in a self-hosted Kubernetes environment this isn’t really a problem. I already back up PostgreSQL. If I ever decide to migrate away from Immich, exporting metadata from PostgreSQL into XMP sidecars would be a relatively straightforward task. I’d still prefer everything important to end up in standard metadata files automatically, but the database itself is no longer something I consider a drawback.

Final thoughts

Despite the rough edges, I’m actually impressed with Immich. The mobile backup works well. External Libraries let me keep my existing folder structure. The interface is fast. And the XMP sidecar support gives me much more confidence that my metadata won’t become trapped inside a single application. Like every self-hosted project, there is a learning curve. Hopefully this article helps make that curve a little shorter.

• Don’t treat library/ as an import directory.
• Keep External Libraries outside UPLOAD_LOCATION.
• Store your photo archive on regular storage; use replicated storage for PostgreSQL.
• Back up both the database and the photo files.
• Prefer open metadata formats (XMP) over application-only metadata.