Implementation guide · verified July 3, 2026
Treat Immich external libraries as indexed storage, not as a backup shortcut.
External libraries are useful when you already have curated photo folders, NAS shares or read-only archives. The risk is operational: Immich stores library records and user metadata in its database, while the original files stay outside the normal upload folder. Your backup and restore plan has to protect both sides.
Fast answer: mount external folders read-only unless Immich must write sidecars or delete files, use the container-visible path as the import path, scan after changes, keep the database backup synchronized with external-folder snapshots, and test restore with the same mount structure.
When external libraries fit
| Use case | Why it fits | Planning warning |
|---|---|---|
| Existing archive | You can index a folder tree without re-uploading everything into Immich. | Moving files later can make Immich treat them as new assets after rescan. |
| Read-only NAS share | Immich can browse and index files while another workflow remains the source of truth. | Network-drive watching may not work; rely on scheduled scans. |
| Curated folders | Folder view and exclusion patterns can preserve a human-managed structure. | Advanced exclusion rules can become hard to reason about; keep them simple. |
| Mixed upload + archive setup | New phone uploads can stay in Immich while old folders remain external. | Your restore checklist must include both Immich's upload folders and external mounts. |
Implementation checklist
- Decide ownership before creating the library. Immich currently assigns each external library to one selected user when the library is created.
- Mount the folder into the server container. The import path must be the path visible inside Docker, not necessarily the host path. For example, a host folder can be mounted as
/mnt/media/archive:roand then added in Immich as/mnt/media/archive. - Prefer read-only mounts. The Immich docs show
:rofor external folders when you do not want Immich to delete files or add sidecar metadata. Remove read-only only when that is a deliberate operating choice. - Verify access from every relevant container. Check that mounts are present for the server and any worker or microservices container that needs to process library files.
- Create the library as an administrator. Add one or more import paths, set simple exclusion patterns if needed, then run a scan.
- Watch the job queues. A successful scan should lead to library, thumbnail and metadata work, not just a completed page click.
- Document the scan interval. Immich has a nightly job and configurable external-library scan schedule. Use automatic watching only as an advanced, experimental choice, especially on network storage.
Backup scope changes
Immich's backup documentation is explicit that database backups contain metadata only; photos and videos still need their own file backup. With external libraries, the database becomes even more important because Immich records paths, albums, descriptions, people and other user metadata while the original files live outside UPLOAD_LOCATION.
| Item | Back it up? | Why |
|---|---|---|
| Immich database backup | Yes | Stores paths and user metadata for uploaded and external assets. |
UPLOAD_LOCATION media folders | Yes | Protects normal uploads, profiles and generated recovery inputs. |
| External library source folders | Yes | These originals are outside Immich's upload folder and are not protected by a database backup. |
| Mount map and compose file | Yes | Restore succeeds faster when the same container-visible paths can be recreated. |
| Generated thumbnails and encoded video | Optional | Can usually be regenerated, but rebuilding them adds practical RTO. |
Restore drill for external libraries
- Pick a matched restore point. Pair a database backup with the external-folder snapshot from the same window.
- Recreate mount paths first. During fresh-install restore, Immich specifically warns that external-library mount settings should reflect the previous structure.
- Restore the database only after files are reachable. Integrity checks and later scans are easier to interpret when the folders already exist.
- Scan and sample. Check albums, map locations, descriptions, people, external-library files and newly uploaded internal-library files separately.
- Measure RTO honestly. Include external-folder restore time, database restore time, scan time, thumbnails, metadata extraction and any manual path fixes.
Common failure modes
- Moved files look new. Immich documents that if a moved external asset returns under an import path, it may be added again as a new file and Immich-only metadata can be lost.
- Deleted source files enter trash. If an external file disappears from disk, Immich moves it to trash on rescan; restoring the original file is required to restore the asset.
- Container path mismatch. The path entered in Immich must match the Docker container path, not the desktop, NAS or host path you personally browse.
- Watcher limits or NAS behavior. File watching is experimental, can hit system watch limits, and may not work well on network drives.
- Database-only backup gives false confidence. A database restore without external source folders is an index with missing originals.
Commercial and source note
This guide does not recommend a NAS brand, cloud provider, sync tool or paid backup service. The commercial decision should come after you know whether external libraries reduce migration effort, how much source data must be protected, and whether your measured restore path meets your RTO/RPO target.
Use the restore drill guide to turn this plan into measured recovery evidence →
实施指南 · 核对于 2026 年 7 月 3 日
把 Immich 外部图库当作“已索引存储”，不要当作备份捷径。
外部图库适合已有整理好的照片目录、NAS 共享或只读档案。真正的风险在运维层面：Immich 把图库记录和用户元数据存在数据库里，但原始文件留在普通上传目录之外。因此备份和恢复计划必须同时保护数据库和外部文件。
快速结论：除非确实需要 Immich 写入 sidecar 或删除文件，否则外部目录优先只读挂载；导入路径要使用容器内可见路径；变更后执行扫描；让数据库备份与外部目录快照保持同一时间窗口；恢复演练时复原同样的挂载结构。
什么时候适合用外部图库
| 场景 | 适合原因 | 规划提醒 |
|---|---|---|
| 已有照片档案 | 可以索引现有目录树，不必全部重新上传进 Immich。 | 之后移动文件可能会让 Immich 在重新扫描后把它们当作新资产。 |
| 只读 NAS 共享 | Immich 可以浏览和索引文件，同时让其他流程继续作为数据源。 | 网络盘上的文件监听可能不可用，应依赖定时扫描。 |
| 人工整理目录 | 文件夹视图和排除规则可以保留人工管理的结构。 | 复杂排除规则会增加排错难度，建议保持简单。 |
| 上传库 + 旧档案混合 | 手机新上传留在 Immich 内部库，旧目录保留为外部图库。 | 恢复清单必须同时包含 Immich 上传目录和外部挂载。 |
实施清单
- 创建前先决定归属用户。Immich 当前在创建外部图库时选择一个用户作为归属。
- 把目录挂载进 server 容器。导入路径必须是 Docker 容器内可见路径，不一定是宿主机路径。例如宿主机目录可挂载为
/mnt/media/archive:ro，然后在 Immich 中添加/mnt/media/archive。 - 优先只读挂载。当你不希望 Immich 删除文件或写入 sidecar 元数据时，Immich 文档示例使用
:ro。只有在明确接受该运维选择时才移除只读限制。 - 确认相关容器都能访问。检查 server 以及需要处理图库文件的 worker 或 microservices 容器是否都有相同挂载。
- 用管理员账号创建图库。添加一个或多个导入路径，必要时设置简单排除规则，然后执行扫描。
- 观察任务队列。成功扫描不只是页面点击完成，还应看到 library、thumbnail 和 metadata 等任务。
- 记录扫描间隔。Immich 有每日任务，也可以配置外部图库扫描计划。文件监听属于高级且实验性的选择，网络存储上尤其要谨慎。
备份范围如何变化
Immich 备份文档明确说明，数据库备份只包含元数据；照片和视频仍然需要单独的文件备份。使用外部图库后，数据库更重要，因为路径、相册、描述、人物等用户元数据在数据库中，而原始文件位于 UPLOAD_LOCATION 之外。
| 项目 | 是否备份 | 原因 |
|---|---|---|
| Immich 数据库备份 | 需要 | 保存上传资产和外部资产的路径与用户元数据。 |
UPLOAD_LOCATION 媒体目录 | 需要 | 保护普通上传、头像和恢复所需输入。 |
| 外部图库源目录 | 需要 | 这些原始文件在 Immich 上传目录之外，数据库备份不会保护它们。 |
| 挂载映射和 compose 文件 | 需要 | 能复原同样的容器内路径，恢复速度会快得多。 |
| 缩略图和转码视频 | 可选 | 通常可以重建，但重建会增加实际 RTO。 |
外部图库恢复演练
- 选择匹配的恢复点。把数据库备份与同一时间窗口的外部目录快照配对。
- 先复原挂载路径。Immich 在全新安装恢复说明中特别提醒，使用过外部图库时，新
docker-compose.yml的挂载设置应反映原有结构。 - 文件可访问后再恢复数据库。目录已经存在时，完整性检查和后续扫描更容易判断。
- 扫描并抽样。分别检查相册、地图位置、描述、人物、外部图库文件和内部上传文件。
- 诚实计量 RTO。把外部目录恢复时间、数据库恢复时间、扫描时间、缩略图、元数据提取和手工路径修复都算进去。
常见故障模式
- 移动后的文件像新文件。Immich 文档说明，外部资产移动后再回到导入路径，可能会被当作新资产加入，并且 Immich 内部元数据可能丢失。
- 源文件删除会进入回收站。外部文件从磁盘消失后，Immich 会在重新扫描时把资产移入回收站；要恢复资产，需要恢复原始文件。
- 容器路径不匹配。在 Immich 中填写的路径必须匹配 Docker 容器路径，而不是你在桌面、NAS 或宿主机上看到的路径。
- 监听限制或 NAS 行为。文件监听是实验性功能，可能遇到系统监听数量限制，也可能不适合网络驱动器。
- 只备份数据库会带来虚假安全感。没有外部源目录的数据库恢复，只会得到一个缺少原始文件的索引。
商业与来源说明
本文不推荐 NAS 品牌、云服务商、同步工具或付费备份服务。商业选择应在明确外部图库是否降低迁移工作量、需要保护多少源数据，以及实测恢复路径是否满足 RTO/RPO 目标之后再做。