Skip to content
Go back

Immich External Libraries Without Moving

By KingPin 15 min read
Immich External Libraries Without Moving
Contents

You have fifteen years of photos in a folder tree you spent real effort on. 2014/Italy/, Family/Birthdays/, a Raw/ directory you refuse to talk about. Now you want Immich’s timeline, map, and search on top of all that, and the upload flow wants to copy every file into its own storage layout. Your NAS has 4 TB of photos and your Immich box has 500 GB of SSD. The math does not work.

Use an external library when something else already owns your files: a NAS share, another app like PhotoPrism or digiKam, or a folder tree you will not give up. Use uploads when Immich should be the source of truth, such as phone backups. Most people end up running both, and that is the right answer.

Full example: Clone the working files at github.com/KingPin/sumguy-examples/self-hosting/immich-external-libraries

External library vs upload library

An upload library is the default. Your phone sends a file, Immich writes it under its own /data volume, and the storage template can rename and sort it. Immich owns that file.

An external library flips that. The Immich docs put it plainly: external libraries track assets stored in the filesystem outside of Immich. When you scan, Immich reads your videos and photos from disk and creates matching assets. They show up in the main timeline, on the map, and in albums like any other asset.

The one-line rule: if you would be upset to see Immich rearrange the files, use an external library. Using an upload library for a pre-organized archive is like hiring a forklift operator to reshelve your warehouse by their own system. The pallets get moved, and nobody can find anything the next morning.

Here is how I pick:

SituationUse
Phone camera backupUpload
Family members dumping photos from their phonesUpload
Years of folders on a NASExternal
Another app (PhotoPrism, digiKam) still manages the filesExternal
Storage too small to hold a second copyExternal
You want Immich to rename and sort filesUpload

The storage template, which sorts uploaded files into folders by date and so on, does not touch external assets. The Immich server code skips them in the move step with the comment “External assets are not affected by storage template”. Good news if you wanted that. Bad news if you wanted tidy folders out of Immich.

Mount the folders in docker-compose

Immich can only scan what the container can see. The stock immich-server service has one data volume (${UPLOAD_LOCATION}:/data), so you add your photo folders next to it. The docs show the pattern; this version uses generic paths:

docker-compose.yml
immich-server:
volumes:
- ${UPLOAD_LOCATION}:/data
- /srv/nas/pictures:/mnt/photos/pictures:ro
- /srv/nas/videos:/mnt/photos/videos:ro

The left side is the host path. The right side is the container path. Remember both, because Immich only ever sees the right side.

Run docker compose up -d to apply it. Then verify the mount from inside, before you touch the web UI:

Terminal window
docker exec -it immich_server bash
ls /mnt/photos/pictures

The docs call out the same check. If you run a dedicated microservices container, it needs the same mount too. The troubleshooting list in the docs also says to avoid symlinks inside your import folders and to avoid linking across Docker mounts. Immich’s file crawler does not follow symlinks at all, so a symlinked folder is skipped even when it points inside the same mount. Check permissions as well: the user inside the container needs read access to every directory and file.

To :ro or not to :ro

The docs warn that a volume without :ro means Immich will be able to delete the files in that folder. With :ro, the docs say, images cannot be deleted in the web UI, and no XMP sidecars are written.

There is a second consequence in the XMP sidecar docs. On a read-only mount, metadata edits “will silently fail” with no warning. You edit a description or rating, the UI looks fine, and nothing sticks. The docs link to an issue about it.

So pick on purpose:

Also separate in your head where Immich writes its own output. Thumbnails and encoded videos go under its own storage folders (thumbs and encoded-video in the server source), which live under UPLOAD_LOCATION. Your read-only photo mount never needs write access for that.

Create the library and import paths

Only an admin can do this. In the web UI:

  1. Click your avatar, then Administration -> External Libraries.
  2. Click Create Library.
  3. Pick the owner. The docs say you cannot change it later.
  4. In the Folders section, click Add and enter /mnt/photos/pictures.
  5. Click Scan.

The path is the container path, not the host path. The docs repeat this with a NAS example: you must enter the mounted path, not the original, “since all paths have to be what the Docker containers see”. If you type /srv/nas/pictures here, Immich will tell you the path is not accessible, because inside the container it does not exist.

Import paths behave like this, per the docs:

One more limit: the docs note that an external library belongs to a single user, picked at creation. If your partner wants to see the same photos, partner sharing or a shared album covers it. If they need to own the assets, create a second library on the same mount, owned by them. You get two sets of assets, with separate albums and edits for each.

You can also plan libraries by what you want to exclude. In the docs example, a trip folder gets its own library because it has a Raw subfolder to skip, while videos and old photos share a library. That is a decent rule: one exclusion list per library, so group folders that need the same filters.

Exclusion patterns

A new library starts with a few exclusion patterns already filled in: Synology @eaDir, macOS ._* files, #recycle, #snapshot, and Syncthing’s .stversions and .stfolder. Hidden dotfiles are skipped too. Everything else in the import paths gets added, unless your own exclusion patterns say otherwise. They are glob patterns matched against the full file path, set on the library’s scan settings page. Matching files are not imported, and files already imported get offlined and moved to trash on the next scan.

Examples straight from the docs:

exclusion patterns
**/*.tif
**/hidden.jpg
**/Raw/**
**/*.{tif,jpg}
**/*.{arw,dng}

What they do, in order: skip all .tif files, skip any file named hidden.jpg, skip everything under any Raw directory, skip .tif and .jpg, and skip .arw and .dng raw files. Patterns are case-insensitive, so **/*.{arw,dng} also skips .ARW and .DnG.

* matches within one filename or directory name. ** matches zero or more subdirectories, and at the end of a pattern it also matches every file below. Synology users get a head start: new libraries already exclude **/@eaDir/**, the thumbnail folders a NAS litters everywhere. If you write your own pattern with @ or another special character, the docs suggest escaping it:

escaped special character
**/\@eaDir/**

The syntax is Picomatch, so that documentation is the place to look when a pattern misbehaves.

Make this change before the first scan if you can. A raw-file import you have to offline later is just wasted thumbnail jobs.

Scan interval, nightly job, and watching

Immich does not notice new files by itself unless you turn on watching. Per the docs, if a file changes outside Immich, you need to scan the library for the change to show up.

Nightly job. There is a scan job that runs once a day, and its schedule is configurable. The default config shows "enabled": true and "cronExpression": "0 0 * * *", which is midnight every day in the container’s time zone (UTC unless you set TZ). Change it under Administration -> Settings -> External Library, using a preset or a cron expression. The same nightly job also cleans up libraries stuck in deletion.

Manual scan. Click Scan on a library, or Scan All Libraries in the library list.

Watching (experimental). The docs label this “EXPERIMENTAL” and “for advanced users only”. If enabled, new assets import automatically without a rescan. The default config has library.watch.enabled set to false. For most home labs this is the deciding fact: the docs say that if your photos are on a network drive, automatic file watching “likely won’t work”, and you should rely on the periodic refresh instead.

That makes sense. Filesystem watching relies on change notifications from the kernel, and a share mounted over the network does not reliably deliver them when another machine changes files. So on NFS or SMB, set the cron and forget watching.

If you do watch a local disk and see ENOSPC errors in the log, raise the inotify limit. The docs give the sysctl key and an old default of 8192. Current kernels scale the default with RAM, so check yours first and only raise it:

Terminal window
# check the current limit
sysctl fs.inotify.max_user_watches
# raise it (pick a number above your file count)
echo 'fs.inotify.max_user_watches=524288' | sudo tee /etc/sysctl.d/60-inotify.conf
sudo sysctl --system

The docs also warn that Immich has to watch all files in your import paths, including ignored ones. A rare hang of the watcher can block startup; the docs describe a recovery path involving the admin settings. If you see that, read the “Automatic watching” troubleshooting section.

What happens when files move or vanish

External libraries are a mirror of the disk. When the disk changes, the mirror follows on the next scan, and that has consequences.

Delete a file on disk. Immich moves the asset to trash on rescan. To restore it, you restore the original file. After 30 days the asset is removed from trash and any Immich-side metadata changes are lost. With file watching on, a deletion the watcher catches skips the trash and removes the asset right away.

Move a file on disk. Immich sees a new asset. Per the docs, if you move an asset within the library, all the metadata you added in Immich (album membership, description edits) is lost on rescan, “because the asset is considered a new asset after the move”. The docs call this a known issue to be fixed in a future release.

Change an import path. If an edit leaves a file outside any import path, it is removed from the library the same way a deleted file is. Move the file back into an import path and it is re-added as new.

Exclude a pattern after import. Matching files are offlined and moved to trash on the next scan, the same as deleted files. Remove the pattern and rescan within 30 days to get them back.

The rule I follow: do not reorganize an external library folder after you have curated it in Immich. Sort and rename first, scan second. If you must reorganize, assume your albums need rebuilding.

One browser gotcha from the docs: aggressive caching can leave a refreshed asset looking stale in the web view. The docs suggest an empty-cache hard reload in Chrome.

What you can and cannot do with external assets

Per the docs, external assets show in the timeline and behave like any other asset, including viewing on the map and adding to albums. The limit is where metadata lives. If you add an asset to an album or edit its description, that metadata is “only stored inside Immich” and is not written into the file on disk. With a read-write mount and sidecars, edits to things like rating, tags, and description can be written to .xmp files next to the originals. With a read-only mount, they silently fail.

So treat Immich’s database as the owner of your albums and edits, and your disk as the owner of the pixels. Back up both. The folder backup does not contain your albums.

There is also Folder view, an extra view that works like a file explorer over your library. The docs enable it under Account Settings > Features > Folders and call it handy for a highly curated external library. If you came from a folder-obsessed workflow, turn it on.

NFS and SMB mount gotchas

You have two ways to get a NAS share into the container. The sane one is to mount it on the Docker host and bind-mount the host path in compose. A host-side NFS mount in /etc/fstab looks like this (placeholder hostname and paths):

/etc/fstab
nas.local:/export/pictures /srv/nas/pictures nfs ro,_netdev,nofail 0 0

Why those options: ro matches your :ro bind, _netdev waits for the network, and nofail keeps the box booting if the NAS is down. Skip x-systemd.automount here: an autofs mount point bind-mounted into a container is a known source of “Too many levels of symbolic links” errors. Mount it, then check it before starting Immich:

Terminal window
sudo systemctl daemon-reload
sudo mount /srv/nas/pictures
ls /srv/nas/pictures | head

Three gotchas:

  1. Start order. If Docker starts before the share is mounted, the container binds the empty mount point directory. Immich then sees an empty folder, and a scan marks every asset offline and moves it to trash. Compose depends_on cannot fix this, because it only orders containers. Add a systemd drop-in so Docker waits for the mount (sudo systemctl edit docker.service, then add RequiresMountsFor=/srv/nas/pictures under [Unit]). If it happens anyway, remount the share and rescan within 30 days: the assets come back out of trash.
  2. No watching. The docs already told you. Set a cron.
  3. Permissions. The container user must be able to read every directory. A share that lists fine as root can fail for a non-root container user. Check from inside the container with ls, as the docs suggest.

The database is a different story. The stock .env says network shares are not supported for DB_DATA_LOCATION. Photos on NFS are fine, Postgres on NFS is not.

Run both library types together

You do not have to choose. The setup I would run:

.env
# Immich's own storage: uploads, thumbnails, encoded video. Local SSD.
UPLOAD_LOCATION=/srv/immich/library
# Postgres lives on local disk. Never a network share.
DB_DATA_LOCATION=/srv/immich/postgres
IMMICH_VERSION=v3
docker-compose.yml
immich-server:
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
# external libraries, read-only
- /srv/nas/pictures:/mnt/photos/pictures:ro
- /srv/nas/videos:/mnt/photos/videos:ro

Phones upload into the upload library, and the storage template tidies those. The archive stays an external library with :ro, a cron scan, and an exclusion list. Both appear in one timeline. The current release is v3.4.2 (released 2026-11-18). The stock example.env sets IMMICH_VERSION=v3, which tracks the major version. Pin a full version if you want upgrades to be a decision rather than an accident.

Your 2 AM self will thank you for the :ro. Being unable to delete a photo by accident is a trade you will not regret.

Common Questions

Does Immich move or rename files in an external library?

No. Immich leaves external library files where they are. The server code skips external assets in the storage template move step, so no renaming or sorting happens. Immich only writes thumbnails and encoded video into its own storage folders. With a read-write mount, it can write XMP sidecar files next to originals.

Can I convert external library assets into uploaded assets later?

No, Immich has no conversion feature. The practical route is to upload copies of the files through Immich, then delete the external library. Deleting a library immediately deletes its assets inside Immich, and albums built on them need rebuilding. Plan on double the storage during the switch.

What happens if I change the NAS path or mount point later?

If the container path changes, Immich treats the files as gone. If the new mount path is not an import path, the assets leave the library like deleted files. Keep the container path (/mnt/photos/pictures) stable and change only the host side of the compose bind mount, then rescan. The import path still matches, so the assets stay in place.

Can two Immich users share one external library?

No. The docs state an external library can belong to a single user, chosen when the library is created and not changeable afterward. To show the same photos to a second user, use partner sharing or a shared album. If that user must own the assets, create another library with the same import path owned by them.


Share this post on:

Send a Webmention

Written about this post on your own site? Send a webmention and it'll show up above once verified.


Next Post
Recyclarr: TRaSH Guides for Sonarr/Radarr

Discussion

Powered by Garrul . Sign in with GitHub or Google, or post anonymously.

Related Posts