Open Nav

How to Use a Remounted Drive in Immich for Storage Configuration

Running Immich on a server becomes significantly more reliable when photo and video storage is placed on a dedicated drive instead of the operating system disk. A remounted drive can provide more capacity, better organization, and easier backup planning, but it must be connected to Immich in a consistent and deliberate way. The key is to make sure the drive mounts at the same path every time, Docker sees that path correctly, and Immich has permission to read and write the files it manages.

TLDR: Mount the drive permanently using a stable path such as /mnt/immich-library, preferably through /etc/fstab with the drive UUID. Then point Immich’s Docker volume or UPLOAD_LOCATION setting to that mounted location and restart the stack. Confirm permissions, test uploads, and avoid changing the storage path casually after Immich is already in use. Always back up both the media files and the Immich database before moving or remounting storage.

Understanding How Immich Uses Storage

Immich is typically deployed with Docker Compose, and Docker containers do not automatically see every folder on the host system. A host directory must be mapped into the container through a bind mount or Docker volume. In most standard Immich installations, uploaded photos and videos are stored on the host path defined by the UPLOAD_LOCATION variable in the .env file, and then mounted into the Immich server container at an internal container path such as /usr/src/app/upload.

This means the physical drive itself is not what Immich cares about directly. Immich cares that the configured host path exists, is mounted, and remains available. If you remount a drive from one location to another, Immich will continue looking at the path configured in Docker Compose. If that path now points to an empty directory or an unmounted location, Immich may appear to lose access to files, even though the files are still present on the drive.

Before making changes, stop and identify three things:

  • The current Immich upload location on the host.
  • The new mount point of the remounted drive.
  • The Docker Compose volume mapping used by Immich.

Choose a Stable Mount Point

A reliable Immich storage configuration begins with a stable mount point. Avoid temporary paths such as /media/user/DriveName if the server is expected to run unattended. These desktop-style mount paths can change depending on the user session, drive label, or automount behavior. A better approach is to create a dedicated directory under /mnt or /srv.

For example:

sudo mkdir -p /mnt/immich-library

This path is clear, predictable, and easy to reference in scripts, Docker Compose files, and backup documentation. If you later replace the disk, you can mount the new disk at the same location and avoid changing Immich’s internal configuration.

Mount the Drive Permanently with fstab

For a server, manually mounting a drive after every reboot is not acceptable. Immich may start before the drive is mounted, causing Docker to create an empty directory at the expected path. This is a common and serious mistake because new uploads may then be written to the operating system disk instead of the storage drive.

Use the drive’s UUID rather than a device name such as /dev/sdb1. Device names can change between boots, while UUIDs are designed to remain stable.

Find the UUID:

lsblk -f

Then edit /etc/fstab:

sudo nano /etc/fstab

An example entry for an ext4 drive might look like this:

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

For an NTFS drive, the filesystem type and options will differ, but for Linux servers, ext4 or xfs is generally preferred for a permanent Immich storage drive. These filesystems handle Linux permissions more naturally and are usually better suited to always-on services.

After editing fstab, test it without rebooting:

sudo mount -a

Then confirm the drive is mounted:

findmnt /mnt/immich-library
df -h /mnt/immich-library

If these commands show the expected device and capacity, the mount configuration is likely correct.

Prepare the Directory Structure

It is wise to create a dedicated subdirectory for Immich rather than using the root of the drive. This keeps the drive organized and reduces the chance of mixing unrelated files with application-managed data.

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

You may also create directories for external libraries, backups, exports, or staging:

sudo mkdir -p /mnt/immich-library/external
sudo mkdir -p /mnt/immich-library/backups

A clean structure might look like this:

  • /mnt/immich-library/upload for Immich-managed uploaded assets.
  • /mnt/immich-library/external for read-only or imported photo collections.
  • /mnt/immich-library/backups for local backup staging, if appropriate.

Do not place database files casually on the same drive without understanding your backup and performance requirements. Immich’s PostgreSQL database is just as important as the media files because it stores metadata, albums, users, and asset references.

Update the Immich Environment Configuration

In a standard Docker Compose installation, Immich uses a .env file located in the same directory as docker-compose.yml. Open this file and locate UPLOAD_LOCATION.

For example:

UPLOAD_LOCATION=/mnt/immich-library/upload

This tells Docker Compose where the host-side upload folder is located. In the Compose file, that variable is commonly used in a volume mapping similar to this:

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

The left side is the host path. The right side is the container path. You usually should not change the container path unless you know the Immich image expects a different location. The safest approach is to change only the host-side value in .env.

Move Existing Immich Files Safely

If Immich is already running and contains existing uploads, you must move the files carefully. The safest sequence is:

  1. Back up the PostgreSQL database.
  2. Stop the Immich Docker Compose stack.
  3. Copy or move the existing upload directory to the mounted drive.
  4. Update UPLOAD_LOCATION.
  5. Start Immich again.
  6. Verify that old assets and new uploads work correctly.

Stop Immich from the directory containing your Compose file:

docker compose down

Copy files with permissions preserved:

sudo rsync -aHAX --info=progress2 /old/immich/upload/ /mnt/immich-library/upload/

The trailing slashes matter: this copies the contents of the old upload directory into the new upload directory. After confirming everything works, you can remove the old copy, but it is prudent to keep it temporarily until you are confident the migration succeeded.

Set Correct Ownership and Permissions

Permissions are a frequent cause of failed uploads, missing thumbnails, or background job errors. The Immich container must be able to read and write to the upload directory. The exact user ID depends on the container image and deployment method, so inspect your environment rather than guessing.

As a practical starting point, check the owner of files created by Immich in the previous upload directory. Then apply equivalent ownership to the new directory. For example, if your deployment writes as user and group ID 1000:1000:

sudo chown -R 1000:1000 /mnt/immich-library/upload
sudo chmod -R u+rwX,g+rwX /mnt/immich-library/upload

On systems using SELinux, such as some Fedora, CentOS, or Rocky Linux installations, a normal bind mount may still fail because of security labels. In that case, Docker volume options such as :Z or :z may be required, depending on whether the directory is shared between containers. Use these options carefully and according to your distribution’s Docker guidance.

Restart Immich and Validate the Configuration

After the mount point, files, permissions, and environment variables are in place, start the stack again:

docker compose up -d

Then check container status:

docker compose ps

Review logs for storage or permission errors:

docker compose logs -f immich-server

Validation should include more than simply opening the web interface. Perform a controlled test:

  • Upload a small image from the web or mobile app.
  • Confirm the asset appears in Immich.
  • Check that a new file was written under /mnt/immich-library/upload.
  • Restart the server or Docker stack and confirm the media remains accessible.

This test confirms that Immich is not writing to an accidental empty directory on the operating system disk.

Using a Remounted Drive for External Libraries

Immich can also index external libraries, depending on your configuration and version. An external library is different from the upload location: uploaded assets are managed by Immich, while an external library usually points to an existing folder of photos and videos. If your remounted drive contains a pre-existing archive, you may want to expose it to Immich as a separate mount.

For example, your Compose file might include a read-only mapping:

volumes:
  - /mnt/immich-library/external:/usr/src/app/external:ro

The :ro option makes the mount read-only inside the container, which is often sensible for archival collections. You would then configure the external library path inside Immich using the container path, such as /usr/src/app/external, not the host path. This distinction is important: Immich runs inside the container and can only see the paths mapped into that container.

Image not found in postmeta

Avoid Common Mistakes

Several storage problems are predictable and preventable. The most serious is allowing Docker to start before the drive is mounted. If the target directory exists but the drive is absent, Docker may use the empty mount point directory on the system disk. To reduce this risk, ensure the drive is mounted through fstab, use nofail only when appropriate, and consider service ordering if you use systemd to manage Docker startup.

Another common mistake is changing paths inside the container unnecessarily. In most cases, keep Immich’s internal upload path unchanged and only adjust the host-side mount. This preserves compatibility with the supplied Compose configuration and makes troubleshooting easier.

Finally, never treat the media folder alone as a complete backup. Immich requires both the files and the database to restore a working installation. A serious backup plan includes:

  • The Immich upload directory.
  • The PostgreSQL database dump or database volume backup.
  • The docker-compose.yml file.
  • The .env file.
  • Any external library configuration notes.

Final Checklist

Before relying on the remounted drive in production, review the following checklist:

  • Stable mount point: The drive mounts consistently at a path such as /mnt/immich-library.
  • fstab configured: The drive uses a UUID-based entry and survives reboot testing.
  • Immich path updated: UPLOAD_LOCATION points to the mounted drive’s upload directory.
  • Files migrated: Existing uploads were copied with metadata and permissions preserved.
  • Permissions verified: Immich can read and write to the target directory.
  • Docker restarted: The stack was recreated after configuration changes.
  • Upload tested: A new test asset appears both in Immich and on the mounted drive.
  • Backups planned: Media files and the database are both protected.

Using a remounted drive for Immich storage is not difficult, but it must be done with discipline. The storage path should be permanent, the Docker mapping should be explicit, and permissions should be verified rather than assumed. Once configured correctly, a dedicated mounted drive gives Immich the capacity and reliability expected from a serious self-hosted photo management system.

Published on June 4, 2026 under .

Emily Harris