How to Configure Immich to Use a Mounted or Remounted Storage Drive

Jame Miller

5 days ago

Immich stores uploaded photos, videos, thumbnails, encoded video, and profile assets in its configured upload library. When a server gains a larger disk, a USB drive, a NAS mount, or a remounted storage path, the administrator can move Immich’s media storage there by changing the host path that Docker binds into the Immich container. The safest approach is to stop Immich, copy the existing library, mount the drive reliably, update the Immich environment file or Docker Compose volume mapping, then start the stack again and verify that the application can read and write normally.

TLDR: Immich can use a mounted or remounted storage drive by pointing its UPLOAD_LOCATION or Docker volume mapping to the mounted path on the host. The drive should be mounted persistently, preferably by UUID in /etc/fstab, before Docker starts the Immich containers. Existing media should be copied with a tool such as rsync while Immich is stopped, and file permissions should allow the containers to access the library. The database should usually remain on fast, reliable local storage unless the administrator fully understands the risk of moving it.

Understanding What Immich Stores on Disk

Before changing storage locations, the administrator should understand what Immich writes to disk. In a typical Docker Compose installation, Immich uses several containers, including the Immich server, PostgreSQL, Redis, and machine learning services. The most important media directory is normally mounted into the Immich server container at /usr/src/app/upload. On the host, that path is controlled by the UPLOAD_LOCATION variable in the Immich .env file, or by a direct bind mount in docker-compose.yml.

The upload library contains original uploads, thumbnails, encoded videos, profile images, and other generated media files. This directory is the best candidate for a large mounted drive because it grows as users upload photos and videos. By contrast, the PostgreSQL database is more sensitive to latency and corruption. Although it can technically be placed on another disk, it should not be placed on an unreliable USB drive, unstable network mount, or filesystem that may disappear while the containers are running.

Image not found in postmeta

Recommended Storage Layout

A practical Immich setup often separates media storage from application configuration. For example, the administrator may keep Docker Compose files in /opt/immich, keep PostgreSQL data on a local SSD, and place the Immich media library on a larger mounted drive such as /mnt/photos/immich. This makes backups, upgrades, and troubleshooting easier.

Compose directory: /opt/immich or another administrative location.
Immich upload library: /mnt/photos/immich/library or similar.
Database data: /opt/immich/postgres or a fast local disk path.
Backups: a separate destination, not the same drive as the only live copy.

The administrator should avoid using a casual path such as /media/user/DriveName for a server service. Desktop auto-mount paths can change after reboots, logouts, drive label changes, or graphical session changes. A stable server path such as /mnt/immich-storage is generally better.

Mounting the Drive Persistently

If the drive is not already mounted, the administrator should create a stable mount point and mount the drive by UUID. Device names such as /dev/sdb1 can change between boots, while UUIDs are intended to remain stable for the filesystem.

First, the administrator can identify the drive and filesystem UUID:

lsblk -f
blkid

Then a mount point can be created:

sudo mkdir -p /mnt/immich-storage

The /etc/fstab file can then be edited:

sudo nano /etc/fstab

An example entry for an ext4 filesystem may look like this:

UUID=1234abcd-5678-ef00-9999-abcdef123456 /mnt/immich-storage ext4 defaults,nofail 0 2

For an XFS filesystem, the type would be xfs. For a network share, options differ and should be chosen carefully. After saving the file, the administrator can test the mount:

sudo mount -a
findmnt /mnt/immich-storage

If findmnt shows the expected filesystem, the mount is active. The administrator should also reboot once and confirm the drive appears at the same path before trusting it for production photo storage.

Creating the Immich Library Directory

Once the drive is mounted, the Immich library directory should be created. A common layout is:

sudo mkdir -p /mnt/immich-storage/immich/library

Permissions must allow the Docker container to read and write to the directory. Many Docker deployments run containers with root inside the container, but host filesystem permissions still matter, especially on network shares or restrictive mounts. If the server has a dedicated Linux user that manages Docker files, the administrator may assign ownership to that user:

sudo chown -R immich:immich /mnt/immich-storage/immich

If the deployment is managed by another account, the ownership should match that account or the configured container user. The exact choice depends on the installation. The important rule is simple: Immich must be able to create files and directories under the mounted upload location.

Configuring a New Immich Installation

For a new Immich installation, configuration is straightforward. In the directory containing the Immich Docker Compose files, the administrator should open the .env file and set UPLOAD_LOCATION to the mounted drive path:

UPLOAD_LOCATION=/mnt/immich-storage/immich/library

The Docker Compose file usually contains a volume mapping similar to this:

volumes:
  - ${UPLOAD_LOCATION}:/usr/src/app/upload

With this structure, Docker reads the host path from .env and maps it into the container where Immich expects its upload directory. After saving the file, the administrator can start Immich:

docker compose up -d

The administrator should then open the Immich web interface, upload a small test image, and check whether files appear under the mounted library path. A quick host-side check may be performed with:

sudo find /mnt/immich-storage/immich/library -maxdepth 3 -type f | head

Moving an Existing Immich Library to the Mounted Drive

For an existing installation, the administrator should move data carefully. Immich should not be actively writing files while the library is being copied. The safest procedure is to stop the stack first:

cd /opt/immich
docker compose down

Next, the current upload location should be identified. In many installations, it is listed in the .env file:

cat .env | grep UPLOAD_LOCATION

If the current value is something like ./library, it refers to a directory relative to the Compose project directory. The administrator can copy it to the mounted drive with rsync:

sudo rsync -aHAX --info=progress2 /opt/immich/library/ /mnt/immich-storage/immich/library/

The trailing slashes matter. In this example, the contents of the old library directory are copied into the new library directory. The options preserve attributes as much as possible. On filesystems that do not support Linux permissions, some options may need adjustment, but for ext4 or XFS they are appropriate.

After the copy finishes, the administrator should update .env:

UPLOAD_LOCATION=/mnt/immich-storage/immich/library

Then the stack can be started again:

docker compose up -d

Once Immich is running, the web interface should show the same photos and albums as before. The administrator should inspect recent uploads, thumbnails, and video playback. If everything works, the old library directory should not be deleted immediately. It is better to keep it temporarily as a rollback copy until backups are confirmed.

Handling a Remounted Drive or Changed Mount Path

Sometimes the storage drive already contains the Immich library, but it has been remounted at a different host path. For example, it may have moved from /media/storage to /mnt/immich-storage. In that case, the administrator does not need to copy every photo again if the data is already on the same drive. Instead, the Immich configuration must be updated to point to the new mount path.

The administrator should first stop Immich:

docker compose down

Then the drive should be mounted at the intended path and verified:

findmnt /mnt/immich-storage
ls -la /mnt/immich-storage/immich/library

If the expected Immich folders are visible, the .env file can be changed so that UPLOAD_LOCATION matches the new path. After that, the stack can be started again. This process is low-risk as long as the path points to the same library contents and not to an empty directory.

A common mistake occurs when Docker starts before the drive is mounted. If the configured host path does not exist, Docker may create an empty directory at that location. Immich then starts with what appears to be an empty storage area, causing missing file errors or failed thumbnails. To prevent this, the administrator should ensure the drive is mounted before Docker Compose starts and should verify the path before launching the stack.

Making Docker Wait for the Mounted Drive

On a server that starts Immich automatically after boot, mount timing matters. If Docker starts too early, Immich may see an empty folder instead of the real drive. A persistent /etc/fstab entry helps, but some drives or network mounts may still be late.

For a simple local disk, using /etc/fstab with a stable UUID is usually enough. For network storage, the administrator may need systemd mount units, automount options, or service dependencies. If Immich is managed by a custom systemd service, it can include dependencies such as:

RequiresMountsFor=/mnt/immich-storage

This tells systemd that the mount path is required before the service launches. If Immich is started manually, the administrator should still run findmnt or df -h before starting the stack after a reboot.

Using a Mounted Drive as an External Library

Immich also supports external libraries, which are useful when photos already exist in a folder structure and should be indexed instead of imported as regular uploads. In that case, the mounted drive can be passed into the Immich server container as a separate volume. For example:

volumes:
  - ${UPLOAD_LOCATION}:/usr/src/app/upload
  - /mnt/photo-archive:/usr/src/app/external:ro

The :ro suffix makes the mount read-only inside the container, which is often safer for existing photo archives. After adding the volume, the administrator can configure the external library path in Immich as something like /usr/src/app/external. This is different from the upload library. The upload library is where Immich stores managed files; an external library is where Immich scans files that remain in their existing location.

Backups and Safety Checks

Changing storage paths is not a substitute for backups. Immich stores important information both in the media library and in PostgreSQL. A complete backup should include the database dump and the upload library. If only the media files are backed up, albums, users, metadata, assets, and jobs may not be fully recoverable. If only the database is backed up, the original photos and videos may be missing.

The administrator should maintain at least one backup outside the mounted drive. For large libraries, incremental tools such as rsync, restic, borg, or filesystem snapshots can be used. Before deleting the old library path, the administrator should confirm that backups exist and that a restore process has been tested.

Common Troubleshooting Tips

Photos show as broken: The new upload path may be empty, mounted incorrectly, or missing copied files.
Uploads fail: Immich may not have write permission to the mounted directory.
Files disappear after reboot: The drive may not be mounted persistently through /etc/fstab.
Docker created an empty folder: The configured host path did not exist or the drive was not mounted when containers started.
Database errors appear: The administrator should verify that the database path was not accidentally moved to unreliable storage.

FAQ

Can Immich use an external USB drive for storage?: Yes. Immich can store its upload library on a USB drive if the drive is mounted consistently and has reliable power. However, the administrator should avoid disconnecting it while Immich is running and should keep proper backups.
Should the Immich database be moved to the mounted drive too?: Usually not. The upload library is the best candidate for large mounted storage. PostgreSQL should generally stay on fast, stable local storage unless the mounted drive is equally reliable and the administrator understands database recovery.
What path should be changed to move Immich media?: In most Docker Compose installations, the administrator changes UPLOAD_LOCATION in the .env file. That value is mapped to /usr/src/app/upload inside the Immich container.
Why does Immich look empty after changing the path?: The new path may point to an empty directory instead of the copied library. It can also happen if Docker started before the drive was mounted and created a blank folder at the mount location.
Can a NAS share be used for the upload library?: Yes, but it must be mounted reliably and with correct permissions. Network storage can introduce latency and availability problems, so the administrator should test uploads, thumbnail generation, and reboot behavior carefully.
Is an external library the same as the upload location?: No. The upload location is Immich’s managed media storage. An external library is a separate mounted path that Immich scans, often read-only, while the original files remain in their existing folder structure.