Understanding What Immich Stores on Disk<\/h2>\n
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<\/strong>. On the host, that path is controlled by the UPLOAD_LOCATION<\/strong> variable in the Immich .env<\/strong> file, or by a direct bind mount in docker-compose.yml<\/strong>.<\/p>\n 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.<\/p>\nImage not found in postmeta A practical Immich setup often separates media storage from application configuration. For example, the administrator may keep Docker Compose files in \/opt\/immich<\/strong>, keep PostgreSQL data on a local SSD, and place the Immich media library on a larger mounted drive such as \/mnt\/photos\/immich<\/strong>. This makes backups, upgrades, and troubleshooting easier.<\/p>\n The administrator should avoid using a casual path such as \/media\/user\/DriveName<\/strong> 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<\/strong> is generally better.<\/p>\n 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<\/strong> can change between boots, while UUIDs are intended to remain stable for the filesystem.<\/p>\n First, the administrator can identify the drive and filesystem UUID:<\/p>\n Then a mount point can be created:<\/p>\n The \/etc\/fstab<\/strong> file can then be edited:<\/p>\n An example entry for an ext4 filesystem may look like this:<\/p>\n For an XFS filesystem, the type would be xfs<\/strong>. For a network share, options differ and should be chosen carefully. After saving the file, the administrator can test the mount:<\/p>\n If findmnt<\/strong> 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.<\/p>\n Once the drive is mounted, the Immich library directory should be created. A common layout is:<\/p>\n 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:<\/p>\n 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.<\/p>\n For a new Immich installation, configuration is straightforward. In the directory containing the Immich Docker Compose files, the administrator should open the .env<\/strong> file and set UPLOAD_LOCATION<\/strong> to the mounted drive path:<\/p>\n The Docker Compose file usually contains a volume mapping similar to this:<\/p>\n With this structure, Docker reads the host path from .env<\/strong> and maps it into the container where Immich expects its upload directory. After saving the file, the administrator can start Immich:<\/p>\n 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:<\/p>\n 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:<\/p>\n Next, the current upload location should be identified. In many installations, it is listed in the .env<\/strong> file:<\/p>\n If the current value is something like .\/library<\/strong>, it refers to a directory relative to the Compose project directory. The administrator can copy it to the mounted drive with rsync<\/strong>:<\/p>\n 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.<\/p>\n After the copy finishes, the administrator should update .env<\/strong>:<\/p>\n Then the stack can be started again:<\/p>\n 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.<\/p>\n 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<\/strong> to \/mnt\/immich-storage<\/strong>. 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.<\/p>\n The administrator should first stop Immich:<\/p>\n Then the drive should be mounted at the intended path and verified:<\/p>\n If the expected Immich folders are visible, the .env<\/strong> file can be changed so that UPLOAD_LOCATION<\/strong> 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.<\/p>\n 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.<\/p>\n 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<\/strong> entry helps, but some drives or network mounts may still be late.<\/p>\n For a simple local disk, using \/etc\/fstab<\/strong> 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:<\/p>\n This tells systemd that the mount path is required before the service launches. If Immich is started manually, the administrator should still run findmnt<\/strong> or df -h<\/strong> before starting the stack after a reboot.<\/p>\n 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:<\/p>\n The :ro<\/strong> 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<\/strong>. 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.<\/p>\n 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.<\/p>\n The administrator should maintain at least one backup outside the mounted drive. For large libraries, incremental tools such as rsync<\/strong>, restic<\/strong>, borg<\/strong>, 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.<\/p>\n 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\u2019s 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. <\/p>\n
\nRecommended Storage Layout<\/h2>\n
\n
Mounting the Drive Persistently<\/h2>\n
lsblk -f\nblkid<\/code><\/pre>\nsudo mkdir -p \/mnt\/immich-storage<\/code><\/pre>\nsudo nano \/etc\/fstab<\/code><\/pre>\nUUID=1234abcd-5678-ef00-9999-abcdef123456 \/mnt\/immich-storage ext4 defaults,nofail 0 2<\/code><\/pre>\nsudo mount -a\nfindmnt \/mnt\/immich-storage<\/code><\/pre>\nCreating the Immich Library Directory<\/h2>\n
sudo mkdir -p \/mnt\/immich-storage\/immich\/library<\/code><\/pre>\nsudo chown -R immich:immich \/mnt\/immich-storage\/immich<\/code><\/pre>\n![\"\"](\"https:\/\/resizemyimg.com\/blog\/wp-content\/uploads\/2026\/03\/computer-screen-showing-lines-of-code-server-firewall-settings-screen-open-ports-configuration-linux-terminal-firewall-command.jpg\")
\nConfiguring a New Immich Installation<\/h2>\n
UPLOAD_LOCATION=\/mnt\/immich-storage\/immich\/library<\/code><\/pre>\nvolumes:\n - ${UPLOAD_LOCATION}:\/usr\/src\/app\/upload<\/code><\/pre>\ndocker compose up -d<\/code><\/pre>\nsudo find \/mnt\/immich-storage\/immich\/library -maxdepth 3 -type f | head<\/code><\/pre>\nMoving an Existing Immich Library to the Mounted Drive<\/h2>\n
cd \/opt\/immich\ndocker compose down<\/code><\/pre>\ncat .env | grep UPLOAD_LOCATION<\/code><\/pre>\nsudo rsync -aHAX --info=progress2 \/opt\/immich\/library\/ \/mnt\/immich-storage\/immich\/library\/<\/code><\/pre>\nUPLOAD_LOCATION=\/mnt\/immich-storage\/immich\/library<\/code><\/pre>\ndocker compose up -d<\/code><\/pre>\nHandling a Remounted Drive or Changed Mount Path<\/h2>\n
docker compose down<\/code><\/pre>\nfindmnt \/mnt\/immich-storage\nls -la \/mnt\/immich-storage\/immich\/library<\/code><\/pre>\nMaking Docker Wait for the Mounted Drive<\/h2>\n
RequiresMountsFor=\/mnt\/immich-storage<\/code><\/pre>\n![\"\"](\"https:\/\/resizemyimg.com\/blog\/wp-content\/uploads\/2026\/06\/a-golden-docker-logo-on-a-black-background-server-boot-docker-containers-storage-mount.jpg\"){kind=logo}
\nUsing a Mounted Drive as an External Library<\/h2>\n
volumes:\n - ${UPLOAD_LOCATION}:\/usr\/src\/app\/upload\n - \/mnt\/photo-archive:\/usr\/src\/app\/external:ro<\/code><\/pre>\nBackups and Safety Checks<\/h2>\n
Common Troubleshooting Tips<\/h2>\n
\n
FAQ<\/h2>\n
\n