Add an External Photo Library to Immich on ZimaOS

If you already have photos on another HDD or SSD and want Immich on ZimaOS to index them without moving them into Immich's normal upload library, use an External Library. The October 2024 community thread confirmed this workflow: first expose the ZimaOS host folder to the immich-server container, then add the matching container-side path in Immich Administration.

This is different from changing Immich's primary upload storage. A later reply in the same thread asked whether the external disk could become the sole location for all future Immich uploads, but that question was not resolved in the source thread. Current Immich documentation treats these as two separate workflows: External Libraries for existing files, and UPLOAD_LOCATION/custom storage paths for Immich-managed uploads.

What the Original Thread Actually Solved

The original author wanted Immich to recognize photos stored outside its default location. They later reported success with this sequence:

1. Open Immich settings in ZimaOS.
2. Open the immich-server service.
3. Add the ZimaOS host folder as a Docker volume.
4. Use a container-side path such as /home/user/photos1.
5. Open Immich Administration.
6. Create an External Library and add the same container-side path.

A later user explicitly confirmed that this solution worked for them.

Host Path and Immich Path Are Different

The Docker mapping concept is:

ZimaOS host folder → Immich container folder

For example:

/media/Photos:/home/user/photos1:ro

Immich does not scan the ZimaOS host path directly. It can only scan the path visible inside its container:

/home/user/photos1

Use Read-Only Mode for Existing Photo Archives

The original community solution used :ro. Current Immich documentation still recommends read-only mounts when Immich should only index the files:

/media/Photos:/home/user/photos1:ro

Read-only mode prevents Immich from deleting files or writing sidecar metadata into the source folder.

Current Immich External Library documentation

Create the External Library in Immich

After the mount exists, open Immich with an administrator account and go to the External Libraries section. Create a library, select its owner, and add the container path:

/home/user/photos1

Then run a scan. Immich should begin indexing the photos and creating thumbnails and metadata jobs.

Verify the Path Exists Inside the Container

If Immich rejects the library path, confirm that the mount is visible to immich-server. The source thread's core issue was not merely choosing a folder in the Immich UI; Docker first had to expose that folder inside the container.

Current Immich documentation makes the same requirement explicit: the mounted path must exist inside the container before it can be added as an External Library.

Do Not Blindly Copy the Historical Database-Tab Step

The 2024 source post also said to add the same path in the Immich Database tab. That instruction should be treated cautiously today.

Current upstream Immich separates:

• photo/video storage through UPLOAD_LOCATION or external library bind mounts;
• PostgreSQL database storage through DB_DATA_LOCATION.

The database location is not the same thing as the photo-library location. Do not map an arbitrary photo folder into PostgreSQL just because the old ZimaOS package exposed a Database service tab.

External Library vs Primary Immich Storage

The source thread confirmed the first case, not the second.

If You Want the External Drive to Be Immich's Main Storage

Current Immich Docker Compose uses:

UPLOAD_LOCATION=./library

and mounts that host path to /data inside immich-server. Current custom-location documentation explains how to move Immich-managed data to a different host storage location while preserving the expected container paths.

Immich custom storage locations

If important photos already exist in Immich, back up both the database and filesystem before changing the primary storage location.

Keep Database Requirements Separate

The PostgreSQL database has different storage requirements from photo files. Current Immich documentation says network shares are not supported for the database path and the database should use a suitable local filesystem.

Do not move PostgreSQL simply because you are adding an external photo library.

External Libraries Still Need Independent Backups

Immich does not copy the original external-library assets into its normal managed storage. The originals remain on the external disk. If those files are removed from disk, Immich can mark them as missing or remove them from the active library after rescanning.

Back up the source drive independently. Immich's database metadata is not a replacement for a filesystem backup.

Immich External Library Checklist on ZimaOS

1. Identify the existing ZimaOS host folder containing the photos.
2. Open the current Immich app/container settings.
3. Mount the host folder into immich-server.
4. Prefer :ro for an archive that Immich should not modify.
5. Use a clear container path such as /home/user/photos1 or /mnt/media/photos.
6. Open Immich Administration → External Libraries.
7. Add the exact container-side path.
8. Run a library scan.
9. Do not confuse this with moving Immich's primary UPLOAD_LOCATION.
10. Back up the external drive separately.

Immich External Storage FAQ

Did the original solution work?

Yes. The original author reported success, and another user later confirmed the same workflow worked for them.

Does External Library make the external drive Immich's main upload location?

No. External Libraries index files that already exist outside Immich's managed upload storage.

Which path do I enter in Immich?

Use the container-side path from the Docker mount, not the ZimaOS host path.

Should I use :ro?

Yes when the external folder is an archive that Immich should only read. Remove read-only mode only if you intentionally want Immich to modify or delete files there.