Immich Docker Compose: Install and Setup Guide
Install Immich with the official Docker Compose files. Configure storage and .env, verify startup, understand the Builder, and update safely.
On this page
Direct Answer
For a new server, use Immich's release-provided docker-compose.yml and .env together, choose separate media and database locations, then start the stack with the Docker Compose plugin. Docker Compose remains the recommended production deployment. Official installation ↗
Keep PostgreSQL on a local, permission-capable filesystem, ideally an SSD. A photo share on a NAS and PostgreSQL storage are different decisions: the database must not live on a network share. UPLOAD_LOCATION should be a new managed-media directory, not an existing photo collection you want Immich to scan. Use an external library for that collection.
This guide targets a fresh installation verified against stable v3.3.1 on October 14, 2026. The v3 metatag follows stable v3 updates, not release candidates. On an existing installation, follow the update guide instead of overwriting its configuration with these download commands.
Requirements
| Requirement | Current guidance |
|---|---|
| Operating system | Prefer a 64-bit Linux or other Unix-like host, or a full Linux VM |
| CPU | amd64 or arm64; minimum 2 cores, recommended 4 |
| Memory | Minimum 6 GB; 8 GB recommended |
| Restricted-memory option | 4 GB with machine learning disabled |
| v3 amd64 machine learning | CPU exposed to Docker must support x86-64-v2 or later |
| Media capacity | Allow for originals plus generated media; documentation estimates 10–20% overhead on average |
| Database storage | A local filesystem supporting Unix ownership and permissions; never SMB/NFS |
| Runtime | Docker with the Docker Compose plugin; use docker compose, not legacy docker-compose |
Use the current requirements ↗ before pulling images. The old v2.7.5 exception for x86-64-v1 is unsupported and is not a long-term solution for v3 hardware incompatibility.
Install Docker through the official distribution-specific Docker Engine instructions ↗. On Proxmox, run this procedure inside a Linux VM rather than on the hypervisor. Use the Synology guide for its Container Manager workflow, or the TrueNAS guide for the catalog app and dataset setup.
Download official release files
Create a new directory for the deployment configuration:
mkdir ./immich-app
cd ./immich-appIf that directory already contains an Immich installation, stop here and preserve its existing configuration.
Download the official release assets into the new directory:
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.envEach command should produce the named file. Empty files, HTML error pages or failed downloads are not usable configuration. You can instead download both assets in a browser and rename example.env to .env.
The official instructions use the latest release assets. For a reproducible installation, select both files from the same intended release. Official download procedure ↗
Docker Compose Builder
Immich introduced the Docker Compose Builder ↗ with v3.2.0. It helps prepare a customized Compose configuration. Official announcement ↗
Use it when you need help assembling a customized configuration. For a standard installation, the release-file process above remains the officially documented baseline.
Review generated configuration before using it. The Builder does not automatically migrate data, preserve old customizations or make an existing configuration safe to overwrite. Check storage paths and compare changes before replacing anything in a running deployment.
Configure .env and storage
Keep .env beside docker-compose.yml and set the values that matter before startup:
| Setting | What to choose | Important boundary |
|---|---|---|
UPLOAD_LOCATION | A new directory with capacity for managed uploads | Changing it does not move existing data |
DB_DATA_LOCATION | A local database directory | Do not place it on a network share |
DB_PASSWORD | A unique random alphanumeric value | Avoid special characters and spaces in the supplied Compose setup |
IMMICH_VERSION | v3 for stable v3 updates, or an exact release such as v3.3.1 | An exact pin stays fixed until you change it |
TZ | Uncomment and set a suitable timezone identifier when needed | This affects server-local scheduled work |
DB_USERNAME, DB_DATABASE_NAME | Leave the defaults unless deliberately customizing the database | Values must agree with the database service |
The v3.3.1 release maps ${UPLOAD_LOCATION} to /data in immich-server and ${DB_DATA_LOCATION} to /var/lib/postgresql/data in PostgreSQL. Change host-side environment values for normal storage selection; do not casually change those container-side destinations. v3.3.1 Compose configuration ↗
Changing a path in .env does not copy existing data. A wrong mapping can make an existing installation look empty or point it at an unintended filesystem.
If media is on a NAS, ensure the intended share is mounted before startup. Keep the live database on local storage. Windows users should follow the documented filesystem restrictions and named-volume alternative; changing DB_DATA_LOCATION alone does not create the required volume declaration. Windows storage requirements ↗
Service and container architecture
The checked v3.3.1 default Compose file contains four services:
| Compose service | Container name | Role |
|---|---|---|
immich-server | immich_server | Web/API and server processing |
immich-machine-learning | immich_machine_learning | Machine-learning processing |
database | immich_postgres | PostgreSQL with the required extensions |
redis | immich_redis | Cache and queue dependency, currently using Valkey |
The same release declares a persistent model-cache Docker volume and publishes port 2283 for the server. PostgreSQL and Valkey ports are not published to the host. The database and cache are already included; do not add duplicate services because an older tutorial or another platform package shows a different layout. Checked release configuration ↗
Validate and start
From the directory containing both configuration files, validate the resolved Compose configuration:
docker compose config --quietFix YAML, interpolation or file errors before starting. This checks configuration resolution, not whether storage is writable. Do not publish unrestricted configuration output because it can contain secrets. Docker config reference ↗
Start Immich:
docker compose up -dThe command requests startup. It does not prove all services completed initialization. Check their status and logs next.
docker compose ps -a
docker compose logs --tail=100Look for services that exit or repeatedly restart. Read the first relevant error, including the service and path, rather than treating later connection errors as the cause. Compose startup ↗, status ↗, and logs ↗ references are available from the official documentation.
First-run testing
Open http://SERVER-IP:2283 from a browser on the same network, replacing SERVER-IP with the server's reachable address. Choose **Getting Started** and create the first user; that user becomes administrator. Post-installation steps ↗
Configure the mobile app with the same reachable server URL. localhost on a phone refers to the phone, not the server.
Before starting a large import:
- Upload a small selection of photos and a video.
- Confirm the assets appear in the web interface.
- Download an original and play the video.
- Confirm the intended storage is being used.
These are practical acceptance checks. A successful mobile upload does not create an independent backup of server storage.
Start, stop, restart and update
Run lifecycle commands from the active Compose directory.
| Task | Command | Important distinction |
|---|---|---|
| Start or reconcile the stack | docker compose up -d | Creates or recreates services as required |
| Stop services | docker compose stop | Stops containers without removing them |
| Restart existing containers | docker compose restart | Does not apply changed environment or configuration |
| View service states | docker compose ps -a | Includes stopped containers |
| Read recent logs | docker compose logs --tail=100 | Redact private paths and access URLs before sharing |
For an update, read release notes, retain configuration and make a usable Immich backup. Update an exact version pin if you use one, then pull and reconcile the stack:
docker compose pull && docker compose up -dIMMICH_VERSION=v3 selects the stable major-version image track. It does not enable unattended updates. Pulling images does not rewrite docker-compose.yml or .env, and docker compose restart does not apply changed configuration. Official upgrade instructions ↗, Docker restart reference ↗
Immich downgrades are unsupported. Use the update guide for the full maintenance path.
Common problems
| Symptom | Check first |
|---|---|
Unknown -d flag or legacy Compose validation errors | Install the current Docker Engine and Compose plugin; use docker compose |
.env cannot be opened | Correct directory, exact filename, readability and runtime version |
| PostgreSQL repeatedly restarts | Actual DB_DATA_LOCATION, filesystem support and database logs |
| UI is unreachable | Server address, published port, firewall path and server logs |
| Unexpectedly little free media space | Which host filesystem actually backs /data; confirm any NAS mount exists |
Missing .immich marker | Original storage, restored folders and mount permissions before changing markers |
healthcheck.start_interval requires Engine v25 | Whether the deployment uses a historical or customized Compose file |
The checked v3.3.1 default Compose file does not include start_interval. Treat that message as a historical-file diagnostic, not an instruction to edit every current installation.
For mount-marker failures, follow the official integrity documentation ↗. Do not disable checks simply to make startup succeed.
What not to copy from old tutorials
Avoid copying repository main YAML as a release substitute, legacy docker-compose commands, historical container destinations, unrelated database-image changes, or commands that overwrite configuration and remove persistent data.
Do not assume a restart applies changed environment values. Before relying on the installation, record its storage mappings and establish a recoverable database-and-media backup.
FAQ
Is Docker Compose still the recommended way to install Immich?
Yes. The current official installation documentation identifies Docker Compose as the recommended production method.
Do I need the Docker Compose Builder?
No. The release-file installation remains documented for a normal setup. The Builder is an optional aid for preparing customized Compose configuration.
Does IMMICH_VERSION=v3 update Immich automatically?
No. It selects a stable major-version image track. Updating still requires pulling and reconciling the stack, either manually or through separately configured automation.
Can I import photos by copying them into UPLOAD_LOCATION?
No. Managed assets need corresponding database records. Use supported upload tools or configure an external library.
Will changing UPLOAD_LOCATION move my library?
No. It changes the storage source used by the deployment. Moving an existing library requires preserving the data and following the applicable storage procedure.
Why is a database health check missing from an older YAML comparison?
Some older health-check and tuning lines were incorporated into the Immich PostgreSQL image. Their removal from a newer file does not mean the image has no health check. Official VectorChord FAQ ↗
Once the basic stack works, use the reverse-proxy guide for HTTPS access or the hardware-acceleration guide for separate video and machine-learning GPU setup.
Sources
- Docker Compose installation ↗ — Official installation and command examples.
- Requirements ↗ — Official platform and storage requirements.
- v3.3.1 Compose file ↗ — Official release asset; services, mounts and port.
- v3.3.1 environment example ↗ — Official default environment values.
- Docker Compose Builder ↗ — Official custom configuration tool.
- v3.2.0 release ↗ — Builder announcement.
- Post-installation ↗ — Official onboarding workflow.
- Upgrading ↗ — Official version policy and update commands.
- System Integrity ↗ — Official mount checks and generated-file recovery.