Immich is often chosen because it gives households, creators, and administrators a self-hosted way to manage photo and video libraries without surrendering control of personal media. However, the reliability of an Immich installation depends heavily on how storage is mounted. If the application stores uploads, thumbnails, encoded videos, or backups on a path that changes after reboot, disk replacement, container recreation, or operating system updates, the result can be broken libraries, failed uploads, missing files, or even accidental writes to the wrong disk.
TLDR: Immich should always be configured to use persistent mount points that do not change when the server restarts or when disks are reconnected. Administrators should mount drives by UUID, label, or stable systemd mounts rather than relying on device names such as /dev/sdb1. Docker volumes or bind mounts should point to these stable paths, and permissions should be verified before Immich is started. Regular testing, backups, and monitoring help ensure the media library remains safe over time.
Why Persistent Mount Points Matter for Immich
Immich stores valuable data: original uploads, generated thumbnails, transcoded video files, metadata, profile images, and database-related content. While some of this information can be regenerated, the original media files are irreplaceable. A persistent mount point ensures that Immich always sees the same storage location, regardless of how the operating system identifies the physical disk during boot.
On many Linux systems, disks may appear as /dev/sda, /dev/sdb, or /dev/nvme0n1. These names are not guaranteed to remain consistent. If a USB drive is unplugged and reconnected, or if another disk is added, the expected media drive might receive a different device name. If Immich is configured to use a path based on that unstable name, it may fail to find files or create a new empty folder on the root filesystem.
The safest approach is to mount storage at a predictable directory, such as /mnt/immich-library or /srv/immich/photos, and ensure this directory is always mapped to the intended disk before the Immich containers start.
Understanding Immich Storage Paths
In a typical Docker Compose deployment, Immich uses one or more mounted paths for application data. The most important path is commonly assigned through an environment variable such as UPLOAD_LOCATION. This location is then bind-mounted into the Immich container so the application can store uploaded files outside the container filesystem.
A simplified example may look like this:
UPLOAD_LOCATION=/mnt/immich-libraryAnd in a Docker Compose file, the upload location may be mapped like this:
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/uploadThis means the host directory /mnt/immich-library becomes available inside the container at /usr/src/app/upload. If /mnt/immich-library is not actually mounted to the correct disk, Immich may still start and write data there. That is dangerous because the directory could exist on the system disk instead of the intended storage drive.
Choosing a Stable Mount Location
An administrator should choose a clear, permanent mount path for Immich storage. Common choices include:
/mnt/immich-library/media/photos/srv/immich/upload/data/immich
There is no single correct directory, but the chosen path should be easy to recognize and should not be reused for unrelated services. Many administrators prefer /srv for server application data and /mnt for mounted disks. The most important rule is consistency: once Immich is configured to use that path, it should not be changed casually.
It is also wise to avoid mounting directly to a user’s home directory unless the administrator understands the permission implications. Server applications usually run under service users, container users, or mapped user IDs, and home directory permissions can complicate access.
Finding the Disk UUID or Label
To ensure the correct disk is mounted every time, the operating system should identify it by UUID or filesystem label, not by a temporary device name. On Linux, the administrator can run:
lsblk -fThis command displays filesystems, labels, UUIDs, and mount points. Another useful command is:
blkidA UUID is a long unique identifier assigned to a filesystem. It may look similar to this:
UUID=8f3a7c4e-1234-4567-9999-abcd1234ef00Labels can be easier to read, such as IMMICH_STORAGE, but they must be unique enough to avoid confusion. If a disk does not yet have a label, it can usually be assigned with filesystem-specific tools, such as e2label for ext filesystems or ntfslabel for NTFS.
Configuring Mounts with fstab
One of the most common methods for persistent mounting is editing /etc/fstab. This file tells Linux which filesystems should be mounted at boot. A typical entry for an ext4 Immich storage disk might look like this:
UUID=8f3a7c4e-1234-4567-9999-abcd1234ef00 /mnt/immich-library ext4 defaults,nofail 0 2The fields define the filesystem identifier, mount point, filesystem type, mount options, dump setting, and filesystem check order. The nofail option can prevent the server from failing to boot if the disk is temporarily unavailable. However, administrators should use it carefully. If the server continues booting without the disk, Docker may start Immich and create files in an unmounted directory.
To reduce that risk, the administrator can combine stable fstab mounts with service dependencies or mount checks. At minimum, the mount should be tested manually:
sudo mkdir -p /mnt/immich-library
sudo mount -a
findmnt /mnt/immich-libraryIf findmnt returns the expected disk and filesystem, the mount is active. After rebooting, the same command should be run again to verify persistence.
Using systemd Mount Units
Some administrators prefer systemd mount units instead of relying only on fstab. A systemd mount gives more control over ordering, dependencies, and service startup behavior. This can be useful when Immich runs through Docker Compose as a systemd service.
For example, a mount point at /mnt/immich-library corresponds to a unit named mnt-immich\x2dlibrary.mount, though systemd escaping rules can vary. The unit can specify the disk UUID, filesystem type, and mount options. The Docker Compose service can then be configured to require that mount before starting.
This approach is especially helpful for servers where storage is attached over USB, iSCSI, NFS, SMB, or another network-based method. It allows Immich to wait until storage is available rather than starting too early and writing to an empty directory.
Docker Bind Mounts and Named Volumes
Immich deployments usually rely on Docker Compose. Persistent storage can be connected to containers in two main ways: bind mounts and named volumes.
- Bind mounts: A specific host path, such as
/mnt/immich-library, is mounted into the container. This is transparent and easy to back up. - Named volumes: Docker manages the storage location internally. This is convenient but may be less obvious when managing large media libraries.
For Immich media files, bind mounts are commonly preferred because administrators can clearly see where originals are stored. A good configuration maps a persistent host path into the expected container directory. The host path should be mounted and verified before containers start.
A practical Docker Compose snippet may include:
services:
immich-server:
volumes:
- /mnt/immich-library:/usr/src/app/uploadAlternatively, if an environment file is used:
UPLOAD_LOCATION=/mnt/immich-libraryThen the compose file can reference it:
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/uploadThis keeps configuration cleaner and makes it easier to move storage intentionally later.
Preventing Writes to an Unmounted Directory
One of the most serious mistakes is allowing Immich to start when the storage disk is not mounted. If the mount point directory exists but the disk is absent, Linux treats it as a normal directory on the parent filesystem. Immich may then write uploads to the system disk, causing confusion and possibly filling the root partition.
Several safeguards can reduce this risk:
- Use a mount check script before starting Immich.
- Configure systemd dependencies so Docker Compose starts only after the storage mount is active.
- Monitor free space on both the media disk and root filesystem.
- Set restrictive permissions on the empty mount directory before mounting, so services cannot write to it if the actual disk is absent.
For example, the administrator can make the unmounted directory inaccessible:
sudo mkdir -p /mnt/immich-library
sudo chmod 000 /mnt/immich-libraryAfter the real filesystem is mounted, its own permissions apply. This technique helps prevent accidental writes when the mount fails. However, it must be tested carefully, because incorrect permissions can also prevent Immich from writing when the disk is correctly mounted.
Setting Correct Permissions
Even with the correct mount point, Immich must have permission to read and write to the storage directory. Docker containers often run processes as specific user IDs and group IDs. The administrator should inspect the Immich documentation and container configuration to determine which user needs access.
A common approach is to set ownership on the mounted directory to the user and group expected by the container. For example:
sudo chown -R 1000:1000 /mnt/immich-library
sudo chmod -R 775 /mnt/immich-libraryThis is only an example. The correct IDs may differ depending on deployment. Overly permissive permissions such as 777 may appear to solve access problems, but they reduce security and can mask configuration issues. A better practice is to grant only the access Immich actually needs.
Handling External Libraries and Multiple Disks
Immich can also work with external libraries, where existing photo folders are indexed rather than fully imported into the upload directory. Persistent mount points are just as important in this case. If an external library path changes, Immich may lose access to files or report missing assets.
For multiple disks, administrators should create separate stable mount points, such as:
/mnt/photos-archive/mnt/family-media/mnt/video-library
Each disk should be mounted by UUID or label. In Immich, the configured external library path should reference the stable mount point, not a temporary device path. If files are spread across network shares, those shares should also be mounted persistently and made available before Immich scans them.
Testing After Reboots and Updates
Persistent storage should not be assumed; it should be tested. After configuring mounts, the administrator should reboot the server and confirm that everything returns correctly. Useful checks include:
- Running
findmnt /mnt/immich-libraryto confirm the mount is active. - Running
df -hto verify available space and filesystem placement. - Checking
docker compose logsfor storage or permission errors. - Uploading a small test image to Immich and confirming it appears on the intended disk.
- Restarting the containers and confirming previously uploaded files remain available.
After operating system upgrades, Docker updates, kernel updates, or storage changes, the same checks should be repeated. A storage setup that worked for months can fail after hardware changes or a modified boot sequence.
Backups Are Still Required
Persistent mount points improve reliability, but they are not a substitute for backups. A correctly mounted disk can still fail, be accidentally deleted, or suffer filesystem corruption. Immich administrators should back up both the media storage and the database. The database is especially important because it contains relationships between users, albums, assets, metadata, and application state.
A good backup plan usually includes:
- Original media files from the Immich upload directory.
- The PostgreSQL database used by Immich.
- Docker Compose files and environment files needed to recreate the deployment.
- External library paths if Immich indexes existing media folders.
- Offsite or offline copies for protection against theft, ransomware, or hardware failure.
Backups should be restored in a test environment occasionally. A backup that has never been tested is only a hopeful assumption.
Best Practices Summary
Administrators who want Immich to use persistent mount points should follow a clear process. First, the storage disk should be formatted with a reliable filesystem and assigned a UUID or label. Next, it should be mounted to a permanent directory. Then Docker Compose should bind that directory into Immich. Finally, startup ordering, permissions, monitoring, and backups should be verified.
The key principle is simple: Immich should never depend on temporary device names or uncertain storage availability. Its media path should always refer to a stable, verified mount point that survives reboots and hardware changes.
FAQ
Why should Immich not use /dev/sdb1 directly?
Device names such as /dev/sdb1 can change after rebooting, adding disks, or reconnecting USB storage. Immich should use a stable mounted directory that is linked to a UUID or label instead.
What is the best mount point for Immich storage?
There is no universal best path, but common choices include /mnt/immich-library, /srv/immich/upload, or /data/immich. The path should be consistent, clearly named, and dedicated to Immich storage.
Can Immich use a network share for storage?
Yes, but the network share should be mounted persistently and made available before Immich starts. Systemd dependencies are often useful for NFS, SMB, or other network storage.
What happens if Immich starts before the disk is mounted?
Immich may write files to the empty mount directory on the system disk. This can cause misplaced uploads, missing files after the real disk is mounted, and a full root filesystem.
Should permissions be set to 777?
Usually not. While 777 may bypass permission errors, it is not a secure long-term solution. The administrator should assign ownership and permissions based on the user or group used by the Immich containers.
Are persistent mount points enough to protect the photo library?
No. Persistent mounts help Immich find the correct storage location, but backups are still required. Both the media files and the Immich database should be backed up regularly.
How can an administrator confirm Immich is using the correct disk?
They can run findmnt, df -h, inspect Docker volume mappings, upload a test file, and verify that the file appears on the intended mounted storage path.
