Photos guide
Immich Docker Compose Setup: Storage Choices You Cannot Fix Later
Install Immich from its official Compose release files and make durable choices for database, uploads, external libraries, and upgrades.
Published and reviewed by OpenAlt · September 22, 2026
Immich Docker Compose setup is easiest when storage roles are decided before deployment. Keep PostgreSQL on a permission-capable local filesystem, give Immich a separate managed upload location, and treat existing photos as an external library. Use the official release files and verify paths and credentials before startup.
Table of Contents
- Decide storage
- Requirements
- Download the official release files
- Configure the environment
- Start and verify
- Complete the first setup
- Managed uploads versus external libraries
- Optional hardware acceleration
- Updates, backups, and rollback
- Common failure modes
- Frequently Asked Questions
Decide storage
Choose storage by role before running Compose. Moving the database later is more disruptive than changing a media path, and each part of Immich has different requirements.
| Component | Recommended role | Main concern |
|---|---|---|
| PostgreSQL database | Local, permission-capable filesystem | Do not use a network share |
| Immich upload path | Dedicated location for managed media | Provide capacity and access |
| External library | Existing folders mounted into Immich | Immich indexes without owning files |
| Backup destination | Separate storage or backup system | Avoid the same failure |
The database decision is the strictest. Official requirements call for a permission-capable local filesystem rather than a network share because database behavior depends on reliable filesystem semantics. Read the official Immich requirements before choosing a NAS path.
Requirements
Immich uses Docker Compose and the official release Compose files. Before starting, confirm Docker is installed, the docker compose subcommand works, and the deployment account can access the intended paths.
Preflight checklist:
- Docker is available.
- PostgreSQL data has a local filesystem location.
- Managed uploads have a dedicated path.
- A strong database password is stored securely.
- Required ports and host access are planned.
- A backup destination is ready before import.
- Existing photo folders are identified for an external library.
A mounted network share is not local storage merely because it appears as a host directory. Review the Immich requirements documentation and Docker Compose installation guide before proceeding.
Download the official release files
Use the official Immich release Compose file and matching environment template in a dedicated project directory. Preserve that directory for status checks, logs, updates, and rollback.
- Create the project directory.
- Download both files from the same release.
- Review the environment variables before editing them.
- Keep the directory as the deployment definition.
Avoid mixing releases or copying an unverified forum example. The official Docker Compose installation instructions define the intended files, commands, and release-specific download process.
Configure the environment
Set the upload location, database location, and database password before starting. The upload path is for Immich-managed media; the database path must be on a permission-capable local filesystem.
- Point the upload location to storage for managed photos and videos.
- Point the database data location to a local host path.
- Replace any example password with a strong value.
- Preserve the variable names in the official environment file.
- Confirm Docker can access both paths.
- Keep a private record of the password and configuration.
Upload storage needs enough capacity and appropriate permissions. Choose the database location conservatively because moving it later requires a controlled migration or restore. See the official Docker Compose guide for variables and the requirements documentation for the filesystem constraint.
Start and verify
Start the stack with the command form specified by the official release instructions. From the project directory, the basic checks are:
docker compose up -d
docker compose ps
docker compose logs
Then inspect service status, review logs if anything exits or restarts, open the web interface at the configured host and port, and confirm recurring connection or database errors are absent.
Use docker compose, as required by the modern Immich instructions, unless your installed tooling explicitly supports another form. If startup fails, inspect the first meaningful error instead of repeatedly restarting. Keep the project directory available for diagnostics, updates, and rollback. Use the official installation page for exact release commands and files.
Complete the first setup
After the services run, create the first administrator account through the web interface. Review application settings, confirm managed-upload behavior, and test the deployment before importing a large collection.
- Open the web interface.
- Register the intended administrator.
- Review settings and storage behavior.
- Decide whether existing photos will be an external library.
- Test a small, non-critical upload or library scan.
A limited test can expose path, permission, or account problems while the deployment is easy to adjust. Follow the official post-install guide for the next steps.
Managed uploads versus external libraries
Use managed uploads when Immich should control storage for new media or organize a new library under its own storage model. Use an external library when existing folders must remain in place, another process manages the files, or Immich should index media without moving it.
External libraries still require deliberate mounts and permissions. Make the host path available to the Immich container as described by the official feature documentation, and ensure the application can read it. Review Immich external libraries before adding a large directory tree.
Managed uploads make Immich’s storage layout part of the deployment; external libraries preserve existing organization but add mount, permission, and change-detection responsibilities.
Optional hardware acceleration
Add hardware acceleration only after the basic deployment starts, authenticates, uploads, and indexes successfully. Acceleration can add device mappings and runtime dependencies. Follow the relevant instructions for the host hardware, keep the change isolated, and reverse it if it causes startup problems. The official Compose installation documentation is the reference for supported changes.
Updates, backups, and rollback
Back up the database and media separately. A running library can still be damaged by disk failure, deletion, filesystem problems, misconfiguration, or an unsuccessful update.
Before updating:
- Record the current Compose files and environment settings.
- Confirm the database backup completes and is locatable.
- Protect managed media and external-library source files separately.
- Note the current and intended releases.
- Keep the previous Compose definition until verification is complete.
Afterward, check service status, logs, web access, login, managed uploads, and external-library visibility. If the new deployment fails, use the documented rollback or restore path instead of changing variables at random. The official Docker Compose guide covers release transitions.
Common failure modes
- Database on a network share: move PostgreSQL data to a permission-capable local filesystem.
- Wrong host path: verify that it exists and matches the environment configuration.
- Permission denied: check ownership, access, and container visibility.
- Mixed release files: download the matching official pair again.
- External library missing: verify the host-to-container mount and read access.
- Service exits: inspect Compose status and logs for the first error.
- Password mismatch: ensure the configured password is consistent and secure.
- Storage growth: distinguish managed uploads from external-library source files.
For the supported setup, use the official Docker Compose installation guide and cross-check storage assumptions against the official requirements.
Frequently Asked Questions
Can PostgreSQL live on a NAS share?
No. Immich’s official requirements specify a permission-capable local filesystem for database storage, not a network share. Keep PostgreSQL data local, and evaluate NAS storage separately for media or backups. See the requirements documentation.
Does Immich replace backups?
No. Immich provides photo-library functionality; it does not remove the need to back up the database and media. Protect managed uploads, external-library source files, and database data according to the recovery plan.
Which Compose command syntax should I use?
Use the docker compose syntax required by the official installation instructions. Follow the official Docker Compose guide rather than mixing command styles.
Can existing photos stay in place?
Yes. Use an external library to index existing folders without moving them into managed uploads. Configure container access and permissions, then follow the external libraries documentation.
Should hardware acceleration be enabled during initial setup?
No. Verify startup, authentication, uploads, and indexing first. Add acceleration afterward using the supported host instructions, keeping the change isolated so it can be reversed if needed.
For a broader comparison, see Immich on OpenAlt, the photo alternatives directory, and the self-host difficulty methodology.