Migrate to external library

[bihius]

I created a script that allows migrating assets from Immich’s internal upload folder directly into an External Library, bypassing the built-in migration function.

What it does

• Finds all non-hidden files in the upload directory
• Moves them into a chosen external library path (e.g. /mnt/external/)
• Updates the asset.originalPath column in PostgreSQL to reflect the new location
• Preserves the original file names, so the library structure can follow user-defined folders and subfolders

Why

This approach makes it possible to:

• Keep all assets outside of Immich’s internal storage, in a transparent folder hierarchy
• Avoid duplication of assets during migration
• Stay independent of Immich’s storage format in case you ever stop using it

Notes

• The script directly modifies the database (UPDATE asset SET "originalPath" = ...). This is not officially supported, but in practice it works reliably if done carefully.
• Use with caution and make backups before running in production.

This could be useful for anyone who wants more control over their file organization and prefers to keep Immich as an indexer/viewer on top of an existing photo library structure.

Link to repo

[themcv]

Definitely interested in this. In my moving to Immich, I attempted to have my wife 2TB library sync via her iPhone (which did not work well), which resulted in having some stuff in the DB and the rest now in external library. I will attempt to give it a try this week.

[bihius]

If you have a Mac or MacBook, I would recommend using osxphotos to export your iCloud library as files. If not, you can also run iCloudpd, but it requires Advanced Data Protection to be turned off.
In my opinion, uploading assets (especially that many) to an external library directly or via Immich CLI is more reliable than uploading via the mobile app or webpage.