Avoid .env Mistakes When Setting Up Immich With Docker Compose 2026

Immich is a self-hosted, open-source photo and video backup platform that gives you a Google Photos-like experience on your own server. It bundles a web server, PostgreSQL database, Redis cache, and a machine learning service into a single Docker Compose stack that you can deploy in minutes. The catch is that nearly every setup failure traces back to one file: the .env file that holds your configuration variables.

If you are setting up Immich with Docker Compose, the .env file is where your upload directory, database password, timezone, and version tag all live. A single typo, a missing rename, or a special character in the wrong place can prevent Immich from starting or silently corrupt your database. After helping dozens of users troubleshoot the same recurring errors in the Immich community, our team put together this guide to walk you through the full setup while avoiding every common .env mistake.

This guide covers the three official setup steps from scratch, then dives deep into the specific .env mistakes that trip people up on Ubuntu, Windows, NAS devices, and VPS deployments. Whether you are running Immich on a home server, a mini PC, or a cloud VPS, the principles are the same: get the Docker Engine right, configure the .env carefully, and always recreate containers after changes.

Quick Summary: The .env Mistakes That Break Immich

Before we walk through the full setup, here is a quick-reference list of the most common Immich Docker Compose .env mistakes and their one-line fixes. Nearly every support question in the Immich community traces back to one of these issues.

• Forgetting to rename example.env to .env — Docker Compose only reads a file named .env, so the example file is invisible to it. Rename it before starting containers.
• Using the wrong Docker package on Ubuntu — The docker.io package ships an older Docker Compose that does not support the -d flag or start_interval. Install Docker Engine from the official repository instead.
• Special characters in DB_PASSWORD — Characters like $, &, and backticks break Docker’s environment variable parsing. Stick to alphanumeric characters and underscores.
• Spaces around the equals sign in .env — Writing DB_PASSWORD = secret includes the spaces in the value. Write DB_PASSWORD=secret with no spaces.
• Relative paths in UPLOAD_LOCATION — Relative paths resolve unpredictably. Always use absolute paths like /home/user/immich/uploads.
• Not recreating containers after editing .env — Restarting containers does not reload environment variables. You must run docker compose up -d --force-recreate.
• Wrong or invalid TZ identifier — Values like EST or UTC+5 do not work. Use IANA timezone names like America/New_York.
• Storing the database on a network share — Immich throws a “network shares not supported” error because PostgreSQL cannot run reliably on NFS or SMB mounts.

If you hit any of these during your setup, jump to the detailed fix in the Common .env Mistakes section below. Otherwise, let us start from the beginning with the prerequisites.

Prerequisites: What You Need Before Starting

Immich requires Docker Engine version 25 or higher with the Compose v2 plugin. If you are on Ubuntu 22.04 or 24.04, the single most important thing you can do is install Docker Engine from the official Docker repository rather than the docker.io package that ships with the distribution. That one choice prevents more startup errors than anything else in this guide.

Here is what you need on your host machine before downloading the Immich files:

• Docker Engine v25+ — Installed from the official Docker repository (not docker.io)
• Docker Compose v2 — Bundled as a Docker plugin with the official Engine install
• At least 4 GB of RAM — More if you plan to run machine learning features like facial recognition
• An SSD for the database — HDDs work for photo storage but PostgreSQL needs fast disk I/O
• A dedicated user account — Avoid running Docker as root for production deployments
• Enough disk space for your photo library — Plus headroom for thumbnails and encoded videos

You can verify your Docker version by running docker --version and docker compose version. If the second command fails or shows a version below 2.0, you have the wrong Docker package and need to switch before proceeding.

Step 1: Download the Immich Docker Compose Files

Immich distributes three files that you need to download into a single directory on your server: docker-compose.yml, example.env, and optionally hwaccel.yml for hardware-accelerated transcoding. All three live in the official Immich GitHub repository and should be downloaded fresh each time you set up a new instance.

Create a directory for Immich and download the files using wget or curl. Here is the standard set of commands from the official documentation:

mkdir -p ./immich-app
cd ./immich-app
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.env
wget -O hwaccel.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.yml

Notice that the second wget command downloads example.env but saves it directly as .env. This is intentional and is the cleanest way to avoid the number one mistake people make: forgetting to rename the file. If you prefer to download example.env under its original name, you must rename it to .env before proceeding.

The three files serve distinct purposes. The docker-compose.yml defines the services, containers, and volumes. The .env file stores your configuration values that get substituted into the compose file at runtime. The hwaccel.yml file is optional and adds hardware transcoding support for Intel QuickSync, Nvidia, or AMD GPUs.

Step 2: Configure Your .env File Without Breaking It

This is the step where most Immich Docker Compose setups go wrong. The .env file uses a strict syntax that Docker Compose parses at startup, and any deviation can cause silent failures or cryptic errors. Our team has seen every possible mistake in this file, so let us walk through each variable carefully.

Open the .env file in your preferred text editor. You will see five key variables that you must customize before starting Immich for the first time. Each one has its own gotchas, so we will cover them individually.

UPLOAD_LOCATION: Where Your Photos Live

The UPLOAD_LOCATION variable tells Immich where to store your original photos and videos on the host filesystem. This value gets mounted as a bind mount inside the containers, so the path must exist and be writable by Docker.

Use an absolute path every time. A relative path like ./uploads resolves relative to the directory where you run docker compose up, which can change depending on your working directory. An absolute path like /mnt/storage/immich/uploads always points to the same location regardless of where you execute commands.

DB_DATA_LOCATION: Where the Database Lives

The DB_DATA_LOCATION variable controls where PostgreSQL stores its data files. This must be on a local SSD for reliable performance. Storing the database on a network share like NFS or SMB causes intermittent corruption and triggers the “network shares not supported” error.

Like UPLOAD_LOCATION, use an absolute path. A common pattern is /home/username/immich/db or a dedicated path on your fastest drive. Make sure the parent directory exists and that Docker has permission to create subdirectories within it.

DB_PASSWORD: The Most Error-Prone Variable

The DB_PASSWORD variable sets the PostgreSQL password for Immich’s internal database user. This is the single most common source of .env parsing errors because Docker’s variable substitution treats certain characters specially.

Stick to alphanumeric characters and underscores only. Avoid dollar signs ($), ampersands (&), backticks, exclamation marks, and parentheses. These characters have special meaning in shell parsing and Docker Compose variable substitution, and including them can break the entire .env file. A password like Immich_DB_2026_Secure is perfectly strong and will never cause parsing issues.

Do not wrap the password in quotes inside the .env file. Docker Compose handles the value as-is, so writing DB_PASSWORD="secret" includes the literal quote characters in the password value.

TZ: Your Timezone Identifier

The TZ variable sets the timezone for all Immich containers. This affects photo timestamps, log times, and scheduled tasks. The value must be a valid IANA timezone identifier, not a POSIX abbreviation.

Use identifiers like America/New_York, Europe/London, Asia/Tokyo, or Australia/Sydney. Do not use abbreviations like EST, GMT, or PST because they are ambiguous and may not resolve correctly. Do not use UTC offsets like UTC-5 either, as Docker does not parse those as timezone identifiers.

IMMICH_VERSION: To Pin or Not to Pin

The IMMICH_VERSION variable controls which Docker image tag Immich pulls. You have three options, and each one is appropriate for a different use case.

• release — Pulls the latest stable release. Best for most users. This is the default value.
• latest — May include release candidates and pre-release builds. Use for testing only.
• v3.1.0 (specific tag) — Pins an exact version. Best for production where you control upgrade timing.

For production deployments, our team recommends pinning a specific version tag. This prevents surprise upgrades from pulling a new image that might have breaking changes. For home server testing, release is fine and gives you the latest stable features.

Step 3: Start Immich With docker compose up -d

Once your .env file is configured, starting Immich is a single command. Make sure you are in the same directory as your docker-compose.yml and .env files, then run:

docker compose up -d

The -d flag starts the containers in detached mode, meaning they run in the background. Docker Compose reads your .env file, substitutes the variables into the docker-compose.yml, and creates the server, PostgreSQL, Redis, and machine learning containers.

Give it a minute or two to pull images and start services. You can check the status with docker compose ps and view logs with docker compose logs -f. Once the server container shows as healthy, open your browser and navigate to http://your-server-ip:2283 to complete the web-based setup.

If you later change any value in the .env file, you must recreate the containers for the change to take effect. Restarting them is not enough. Run docker compose up -d --force-recreate to rebuild the containers with the updated environment variables. The Immich official documentation stresses this point: environment variables are baked into the container at creation time, not at restart time.

Common .env Mistakes and How to Fix Each One

This section covers every .env mistake we have encountered in the Immich community. For each one, we explain exactly why it happens and how to fix it. These are the errors that generate the most support questions on Reddit, GitHub issues, and community forums.

Mistake 1: Forgetting to Rename example.env to .env

This is the most common mistake of all. Docker Compose looks for a file named exactly .env in the same directory as your docker-compose.yml. The file named example.env is invisible to Docker Compose, even if it sits right next to the compose file.

If you forget to rename it, Docker Compose substitutes empty strings for all variables. You will see errors about “unset variables,” or Immich will start with default values that do not match your intended configuration. The fix is simple: rename the file.

mv example.env .env

On Windows, use File Explorer or PowerShell to rename the file. Be aware that Windows Explorer hides file extensions by default, so you might accidentally create .env.txt instead of .env. Enable file extensions in the View menu to avoid this trap.

Mistake 2: Spaces Around the Equals Sign

The .env file syntax does not allow spaces around the equals sign. Writing DB_PASSWORD = secret causes Docker Compose to interpret the password as " secret" with a leading space. PostgreSQL then rejects the connection because the password does not match.

The correct format has no spaces at all: DB_PASSWORD=secret. This rule applies to every variable in the file. If you need a value with spaces (unlikely for Immich variables), wrap the entire value in quotes: VARIABLE="value with spaces".

Mistake 3: Special Characters in DB_PASSWORD

Docker Compose uses the dollar sign ($) for variable substitution, so including it in a password causes the parser to look for a variable name that does not exist. The ampersand (&), backtick, and exclamation mark cause similar issues depending on your shell and Docker version.

The fix is to use only alphanumeric characters and underscores in your DB_PASSWORD. A 20-character password with letters, numbers, and underscores is more than secure enough for an internal database. If you absolutely must use special characters, escape them with a double dollar sign ($$), but this is fragile and not recommended for Immich.

Mistake 4: Relative Paths in UPLOAD_LOCATION

Setting UPLOAD_LOCATION=./uploads seems harmless, but it creates a hidden dependency on your working directory. If you run docker compose up -d from a different directory next time, Docker Compose resolves the relative path against the new location, potentially pointing to a different folder or creating a new empty one.

Always use absolute paths. Change UPLOAD_LOCATION=./uploads to UPLOAD_LOCATION=/home/youruser/immich/uploads. Do the same for DB_DATA_LOCATION. Absolute paths eliminate all ambiguity and make your setup portable across reboots and restarts.

Mistake 5: Wrong or Invalid TZ Identifier

Setting TZ=EST or TZ=GMT does not work reliably because these abbreviations are ambiguous. Docker expects IANA timezone identifiers in the format Area/City. The abbreviation EST could mean Eastern Standard Time in the US or Eastern Standard Time in Australia, and Docker may not resolve it at all.

Use identifiers from the IANA timezone database. For the US East Coast, use America/New_York. For Central Europe, use Europe/Berlin. For India, use Asia/Kolkata. You can find the complete list by running timedatectl list-timezones on Linux or searching the IANA timezone database online.

Mistake 6: Not Recreating Containers After .env Changes

This mistake causes endless confusion. You edit the .env file, restart Immich, and nothing changes. The reason is that Docker Compose bakes environment variables into the container at creation time. Restarting a container reuses the same filesystem and environment, so your new values never take effect.

The fix is to recreate the containers instead of restarting them. Run docker compose up -d --force-recreate after any .env change. This tears down the old containers and builds new ones with the updated environment variables. Your data in volumes and bind mounts is preserved because only the containers are recreated, not the data.

Mistake 7: Storing the Database on a Network Share

Immich throws a “network shares not supported” error when PostgreSQL tries to store data on an NFS or SMB mount. This is not an Immich limitation but a PostgreSQL one: databases require strict file locking and fsync guarantees that network filesystems cannot reliably provide.

The fix is to keep DB_DATA_LOCATION on a local SSD. You can store original photos and videos on a network share if you want, but the database and Redis cache must stay on local storage. If you need more space for uploads, mount the network share at UPLOAD_LOCATION and keep the database local.

Troubleshooting Docker Version and Startup Errors

Some of the most frustrating Immich setup errors have nothing to do with the .env file directly. They come from having the wrong Docker installation or an outdated Compose plugin. Here are the four errors we see most often and their exact fixes.

Error: “unknown shorthand flag: ‘d’ in -d”

This error means you are running the old docker-compose command (with a hyphen) instead of the new docker compose command (without a hyphen). The old docker-compose is Python-based and does not support the same flags as the Go-based Compose v2 plugin.

The fix is twofold. First, use docker compose (space, no hyphen) as the command. Second, make sure you have the Docker Compose v2 plugin installed, which comes bundled with the official Docker Engine installation. If you installed Docker via apt install docker.io on Ubuntu, you likely have the old version and need to switch.

Error: “name does not match regex” for Docker Compose Project Name

This error appears when Docker Compose encounters an invalid project name. It usually happens on older Docker versions that do not support the project naming convention used by newer Immich releases. The project name must match a specific regex pattern, and older Docker installations reject it.

The fix is to upgrade Docker Engine to version 25 or higher. Uninstall the docker.io package if present, then install Docker Engine from the official Docker repository. On Ubuntu, this means adding the Docker GPG key and repository, then running apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin.

Error: “healthcheck.start_interval” Not a Valid Configuration

This error occurs on Docker Engine versions older than 25. The start_interval healthcheck parameter was introduced in Docker Engine v25, and older versions do not recognize it. The Immich docker-compose.yml uses this parameter, so old Docker versions fail to parse the file.

There are two fixes. The quick workaround is to comment out or remove the start_interval line in your docker-compose.yml. This gets Immich running on older Docker, but you miss out on the improved healthcheck behavior. The proper fix is to upgrade Docker Engine to v25 or higher, which fully supports the Immich compose file.

Error: “.env File Not Being Read” Even Though It Is in the Right Directory

This is a stubborn one. You have .env in the same directory as docker-compose.yml, but Docker Compose still reports unset variables. On Windows, the culprit is usually file encoding or hidden extensions: the file might actually be named .env.txt without you realizing it. On Linux, the file might have a BOM (byte order mark) from being edited in a Windows editor.

To diagnose, run ls -la in the directory to confirm the file is named exactly .env. On Linux, check the encoding with file .env and look for “ASCII text” without any mention of BOM. If you see a BOM, re-save the file as plain UTF-8 without BOM using a tool like sed -i '1s/^xEFxBBxBF//' .env.

Frequently Asked Questions

Conclusion

Setting up Immich with Docker Compose without the common .env mistakes comes down to three things: install Docker Engine from the official repository, configure your .env file with absolute paths and safe passwords, and always recreate containers after any change. Get those three right and you avoid 95 percent of the errors that fill Immich support channels.

For production deployments, our team recommends pinning a specific IMMICH_VERSION tag, storing the database on a local SSD, and setting up a reverse proxy with HTTPS before exposing Immich to the internet. Back up your UPLOAD_LOCATION and DB_DATA_LOCATION directories regularly, because Immich does not include a built-in backup mechanism.

Once Immich is running, install the mobile app, point it at your server, and start backing up your photo library to your own hardware. The feeling of owning your data is worth the hour you spent getting the .env file right.