Using an Existing Photo Folder as an Immich External Library

Pinned version: Immich v3.3.5 (GitHub release). Last checked: 2026-10-28.

An Immich external library lets Immich index photos and videos that already live in a folder on disk, without copying them into its own upload storage. You mount the folder into the immich-server container (read-only with :ro), then add the path as the container sees it under Administration → External Libraries. Immich scans it and shows the files in the main timeline.

Everything below comes from Immich's External Libraries documentation (checked 2026-10-28).

External library vs uploads

Once scanned, external assets "look and behave like any other asset", including the map and albums. If you edit a file outside Immich, rescan the library to see the change.

Step 1: Mount the folder read-only

Add a volume line for each folder to the immich-server service in docker-compose.yml. The official example:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
      - /home/user/old-pics:/mnt/media/old-pics:ro

The :ro flag gives Immich read-only access: it can't delete those files from the web UI or write XMP sidecars into the folder. Without :ro, Immich can delete files in that folder.

Apply the change with docker compose up -d. If you run a separate microservices or worker container, give it the same mount.

Step 2: Create the library and add the import path

These steps need the Immich admin account:

1. Click your avatar, then Administration → External Libraries → Create Library.
2. Pick the owner. This can't be changed later.
3. Under Folders, click Add and enter the path inside the container, for example /mnt/media/old-pics, not the host path /home/user/old-pics.
4. Click Scan.

A library can have several import paths. Paths are scanned recursively, and a file that sits in two import paths is added only once.

Step 3: Exclude what you don't want

Exclusion patterns are glob patterns, matched case-insensitively against the full path, and set per library in its scan settings. Examples from the docs:

• **/Raw/** skips every folder named Raw
• **/*.{arw,dng} skips RAW files with those extensions
• **/\@eaDir/** skips Synology's @eaDir thumbnail folders (escape the @)

Synology and other NAS paths

A folder on a NAS works like any other: mount the NAS share on the Docker host, then bind-mount that host path into the container with :ro. Immich's docs say automatic file watching (an experimental setting) "likely won't work" on network drives, so rely on the scheduled scan for NAS folders. You can change the scan schedule under Administration → Settings → External Library.

When a library won't scan

The docs' checklist:

• The volume is mounted correctly in docker-compose.yml, and also in any worker containers.
• The import path matches the container side of the mount.
• No symlinks in the import paths, and no links across Docker mounts.
• File permissions let the container read the files.
• Paths use forward slashes (/).

To check access, open a shell with docker exec -it immich_server bash and run ls on the import path.

What to know before you rely on it

• If a file disappears from disk, Immich moves the asset to trash on the next scan. After 30 days it's removed, along with any Immich-only metadata.
• Moving a file to another folder inside the library makes it a new asset on rescan, and its albums and descriptions are lost.
• Deleting an external library in Immich immediately removes all its assets from Immich. With :ro, the files on disk stay untouched.

Your original folder is still your master copy, so back it up the same way you back up the rest of Immich: see Immich backup and restore.

Related: install Immich with Docker Compose · Nextcloud vs Immich (and running both) · Immich backup and restore

Sources

• Immich docs, External Libraries: https://docs.immich.app/features/libraries/ (checked 2026-10-28)
• Immich v3.3.5 release: https://github.com/immich-app/immich/releases/tag/v3.3.5 (checked 2026-10-28)

Related guides

• Immich Docker Compose Setup (Version-Pinned, Update-Safe)
• Nextcloud vs Immich for Photos (and When to Run Both)
• Immich Backup and Restore: Step-by-Step Guide
• All Immich pages
• Comparisons
• All guides