Immich External Libraries: A Read-Only Photo Archive Guide

Suppose your photos already sit in folders you trust. You want a searchable timeline without handing another application control of the originals. Immich external libraries can index those folders, while a read-only mount restricts writes through that connection. There are limits: indexing adds no backup copy, changes need scanning, and some in-app metadata edits may not persist.

This guide helps you decide whether that arrangement fits your archive. It proposes a small-folder pilot on an existing, authorized Docker installation. The pilot has not been executed; it is not a complete installation tutorial or a search benchmark.

Choose between managed uploads and an external library

When your existing folders should stay authoritative

Start with who controls the originals. An external library tracks files outside Immich's managed storage and creates database assets for browsing. Managed uploads put originals in Immich-managed storage, as described in the storage documentation. Choose according to where you want to maintain the archive.

As the external-library documentation explains, indexing avoids requiring an uploaded managed copy of those originals. You still need space for the database and generated assets. Budget for both.

Jaisen Mathai's practitioner account offers a concrete example: he retains Elodie as his archive organizer and uses read-only external folders with Immich. His EXIF write-back relies on a custom integration. Treat it as his setup, not a built-in capability or an Optijara deployment result.

The distinction between a source and its copies also matters when preparing image exports and linked assets. That guide covers creator handoffs rather than Immich setup, but the ownership decision is related.

Separate the archive, container path, and library owner

A read-only mount is a write boundary, not an access policy

Your host folder has a path. Inside a container, the same folder may have a different path. Neither path tells Immich which account should own the library. Under the ownership and path instructions, you select one owner at creation and cannot change that owner afterward. Administrator access does not make every user an owner.

The :ro suffix prevents Immich from deleting originals or writing sidecars through the source mount. Host applications can still change those files. Viewing permissions and backups need separate attention. Follow the mounting guide: add a distinct external mount, keep ${UPLOAD_LOCATION}:/data, and retain all existing managed mounts.

Here is the proposed read path. No deployment was performed for this article.

The database and generated assets still need writable application storage. Only the source mount is read-only.

Run a small read-only archive pilot

Mount and map a sample folder

Use the proposed Mount, Map, Scan, Verify checklist to keep the first attempt small. It is an editorial framework, not an Immich feature or a tested Optijara process. Before starting, confirm that Docker Compose works and you have administrator authorization. Choose harmless sample media with readable permissions. Leave private production photos out of the pilot.

1. Mount. Add the following entry under the existing immich-server service's volumes list. Replace the uppercase placeholder with the sample folder's absolute host path. Keep every existing managed mount. This illustrative excerpt is incomplete and unexecuted; it cannot serve as a standalone Compose file.

- /ABSOLUTE/HOST/SAMPLE:/mnt/photos-source:ro

Applying the change requires a separate operator action. Follow the official guide for updated mounts. No container restart is reported here.

1. Map. Confirm that /mnt/photos-source is readable inside every relevant server or split-worker container. Check the actual permissions. The troubleshooting guidance calls out missing worker mounts and symlink issues, so do not assume a symlink across mounts will work.

Create the library under Administration > External Libraries and select the intended owner. Enter /mnt/photos-source as the import path. /ABSOLUTE/HOST/SAMPLE belongs to the host; Immich needs the directory visible inside its containers. Stop if that directory is inaccessible.

Scan and verify before expanding

1. Scan. Add exclusions before scanning. For example, use /Raw/ only if you intend to exclude directories named Raw and their contents, not every raw-format file. The documented pattern rules match full paths recursively and are case-insensitive. Then trigger the library scan.

1. Verify. Record what you observe. The table below is a proposed measurement plan, not completed test evidence.

Keep deletion tests and public-link creation outside this pilot. If the owner or access boundary differs from your plan, stop expansion and investigate. Granting write access to get past an error changes the arrangement you meant to test.

A compact planning note can record intent separately from observations. The import-path value below identifies the required path type; enter the actual /mnt/photos-source directory in Immich. This JSON is a note, not application configuration or proof of success.

{
  "workflow": "mount-map-scan-verify",
  "import_path_kind": "container-visible",
  "source_access": "read-only",
  "status": "proposed-unexecuted"
}

Read scans and background jobs without assuming live sync

Discovery is not the same as completed processing

Finding a file is only part of the work. Scans create assets; metadata extraction and thumbnail generation have their own jobs. Search processing also affects readiness. The external-library guide directs administrators to inspect Library, Generate Thumbnails, and Extract Metadata jobs. The worker documentation explains that background processing.

A photo appearing in the timeline does not tell you whether every relevant job finished. Inspect job states and errors before judging search quality. This guide establishes neither a processing duration nor archive completeness.

For a hypothetical check, select a known sample filename and record whether it appears under the intended owner. Retain the import path and job state at inspection time. If the file is absent, save the error context before changing settings. Once you correct the identified issue, repeat the same check. Switching to an easier query would tell you little about whether the correction helped. Even a successful recheck says nothing about unexamined files.

Rescans, schedules, and experimental watching

Outside changes require suitable rescanning or metadata refresh. Immich documents a daily automatic library scan whose schedule administrators can change. Its filesystem watcher is a separate experimental feature for advanced users. The watcher warning says it likely will not work for photos on a network drive. Plan around periodic scans unless you have verified another arrangement for your storage.

For missing or stale assets, work through source visibility and import paths, then inspect exclusions, permissions, and jobs. The same documentation notes that browser caching can delay refreshed views. Keep that possibility in mind, but do not use it to explain away a failed check. Find the cause before adding more folders.

Know what XMP sidecars can and cannot preserve

Supported fields are not the whole library

The general library warning says in-app metadata is not persisted into external media files. The XMP documentation describes complementary sidecar support: selected fields can be read from adjacent sidecars and, with suitable write access, written back to them. That write-back does not directly edit original media.

Supported categories include description and rating, along with date/time, location, and tags. Field mappings and automatic job triggers differ. Album membership and people organization should not be treated as a complete portable XMP format; interface layouts are outside that promise too.

For IMG_0001.jpg, Immich prefers IMG_0001.jpg.xmp over the fallback IMG_0001.xmp when both exist. Selected extracted metadata enters the database. The DISCOVER job links newly found sidecars to media that do not already have one linked; SYNC rereads linked sidecars after external changes. Neither job establishes universal conflict resolution between editors.

The read-only metadata editing warning

Read this warning before trying edits. According to the XMP read-only warning, metadata changes on read-only sidecar-backed assets can silently fail in both the sidecar and the database. An apparent UI change is not evidence that the database saved it.

For this pilot, browse in Immich and author archive metadata in your chosen external tool. Removing :ro to make editing work also permits source-file deletion, as the external-library guide explains. That deserves a deliberate decision, not a troubleshooting shortcut.

Descriptive metadata also serves a different purpose from authorship evidence. For generated or edited media, the visual-content provenance guide covers source records and signed credentials. An Immich description cannot replace those records.

Verify browsing with known files before relying on smart search

Use filenames, folders, and dates as spot-checks

For this pilot, a boring filename check is more useful than an impressive semantic-search demonstration. Start with a known filename or fragment. Then use Full path or folder and an expected time range. These documented search filters let you inspect the chosen sample without interpreting descriptive matches. They remain spot-checks, not proof of complete indexing.

If you need the existing hierarchy, enable the optional folder view under Account Settings > Features > Folders, as described in the library guide. It gives you another way to browse; your external tool still organizes the source.

Contextual CLIP search accepts freeform queries without requiring literal metadata keywords. Use it to find candidates, not to establish complete archive coverage. The documentation recommends considering query languages and model resources. Memory and processing trade-offs vary with model choice, so one attractive result is a poor basis for prescribing a model. Establish filename and path visibility before evaluating descriptive searches.

Avoid the mistakes that detach files from their library history

Moving a file is not a harmless database rename

Settle source organization before spending time on in-app curation. Under the documented move behavior, moving a source file within a library can create a new asset on rescan and lose prior Immich-only metadata or album associations. Do not assume the database will follow a filesystem reorganization.

Deleting a source file moves its asset to trash on rescan. Removing all import-path coverage has the same effect. A trash entry is not a copy of the missing original; restore the source file itself.

Several common mistakes are avoidable:

• If you entered the host path in the UI, replace it with the container-visible import path.
• A mount on the API container alone is insufficient when relevant workers need the same readable source path.
• Correct a missing :ro before scanning more folders.
• Plan periodic scans for your storage rather than assuming the watcher works everywhere.
• Treat apparent metadata edits cautiously under the XMP read-only warning.

Repeat the small pilot whenever an underlying assumption changes.

Set the limits before using a larger archive

Storage, sharing, and ongoing maintenance

Before expanding, confirm the intended owner and readable paths across the relevant containers. Check that the source mount remains read-only and review the sample observations. Resolve unexplained job errors. Agree where metadata will be authored and choose a scan schedule. Any unperformed check stays open.

Indexing adds no copy of your originals. Database dumps contain metadata, not photos or videos, so protect external source folders separately from managed Immich data. Backup and restore procedures are outside this guide.

Viewing permissions need their own review. Immich sharing distinguishes album viewers from editors. Partner access can cover an entire library, while public links offer options such as passwords or expiry. Leave sharing unchanged during the pilot.

Allow for installation maintenance and generated-media storage as well as model resources and job troubleshooting. Review privacy and exposure separately from filesystem write permissions. No savings or security outcome is promised. External indexing fits when you want Immich to browse an archive maintained elsewhere and can accept the metadata limits. If writable synchronization is a requirement, resolve it before expanding.