[Guide/Feature Request] The "Unified Library" Architecture (Dual-Mount Strategy for External + Primary integration)

[moorew]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

The feature

The Problem

Many users migrating to Immich have massive, pre-existing photo libraries meticulously organized in flat YYYY/MM/DD structures. When adopting Immich, it forces a difficult choice:

1. Use an External Library: Great for in-place, read-only scanning of the massive archive without moving files. However, new phone uploads end up in the Primary library, creating a disjointed physical folder structure on the host disk.
2. Use CLI Upload: Puts everything in the Primary library, but requires CPU-intensive hashing and copying of hundreds of thousands of files, which can take days for large archives.
3. The "Admin" Folder Enforcement: Even if you use the Primary library, Immich permanently enforces a user-specific root folder (e.g., admin/) in the upload path, breaking a user's existing flat directory structure.

The Solution: The "Dual-Mount" Architecture

I wanted a single, clean Photo Library folder on my hard drive that contains both my old archive AND my new phone uploads, side-by-side in a single YYYY/MM/DD structure, without duplicating files or waiting days for a CLI import.

I achieved this using a specific Docker volume routing hack that I'm proposing as a standard community guide (or as inspiration for a future native feature to unify External and Primary libraries).

How it works

This architecture splits data into two physical folders on the host:

1. Immich System/: Contains the database, docker-compose.yml, and system overhead (thumbnails, transcoded videos).
2. Photo Library/: Contains ONLY actual photos in a clean YYYY/MM/DD structure.

In the docker-compose.yml, we map the Photo Library twice:

    volumes:
      # 1. Main data mount for system overhead (thumbs, transcodes, etc.)
      - ./upload:/usr/src/app/upload
      
      # 2. THE MAGIC ROUTING HACK (Primary Uploads)
      # Immich forces new uploads into a user folder (e.g., 'admin'). 
      # This routes that internal 'admin' folder directly to the clean Photo Library on the host.
      - /path/to/your/Photo Library:/usr/src/app/upload/library/admin
      
      # 3. THE EXTERNAL SCAN HACK
      # Exposes the exact same Photo Library as a read-only "External" library for fast initial indexing.
      - /path/to/your/Photo Library:/usr/src/app/external:ro

Required UI Steps

Once the container runs, configure the UI to respect this structure:

1. Storage Template: Go to Administration > Settings > Storage Template. Enable it and set the template exactly to: {{y}}/{{MM}}/{{dd}}/{{filename}} (Do not include any library/ prefix).
2. Clear Storage Label: Go to Administration > Users. Edit the user and completely clear the "Storage Label" field.
3. Add External Library: Go to Administration > External Libraries. Add the path /usr/src/app/external and run a scan.

Why this is awesome

• Instant Indexing: The 150k+ archive is indexed instantly via the External Library scanner.
• Unified Disk Structure: Because of the admin sub-mount hack, when a phone uploads a new photo, Immich saves it to /usr/src/app/upload/library/admin/2026/05/06/img.jpg, which seamlessly tunnels to the root /Photo Library/2026/05/06/img.jpg on the host machine.
• No Duplicates: When the external scanner runs its periodic checks, it sees the newly uploaded phone photos, calculates the hash, realizes they are already in the database, and safely ignores them.

I wrote an automated bash script that sets up this entire structure, .env, and docker-compose.yml for a fresh system. I wanted to share this with the community for anyone else struggling to merge massive existing archives with new uploads while keeping their hard drive perfectly organized!

Usage

1. Download setup_immich_unified.sh.
2. Open the script in a text editor and update the 4 configuration variables at the top:

• ROOT_MEDIA_DIR
• DB_PASSWORD
• PUBLIC_SERVER_URL

3. Make the script executable: chmod +x setup_immich_unified.sh
4. Run the script: ./setup_immich_unified.sh
5. Follow the terminal output for the final UI setup steps.

setup_immich_unified.sh

Platform

• Server
• Web
• Mobile

[github-actions[bot]]

This discussion has automatically been closed as it is likely a duplicate. We get a lot of duplicate threads each day, which is why we ask you in the template to confirm that you searched for duplicates before opening one. If you're sure this is not a duplicate, please leave a comment and we will reopen the thread if necessary.