Immich Install Guide: Docker Compose, Requirements, Backups and the Mobile Apps

Short answer: To install Immich, use Docker Compose on a 64-bit Linux machine with at least 6 GB of RAM (8 GB recommended) and 2 CPU cores (4 recommended). Download docker-compose.yml and example.env from Immich’s GitHub releases, rename the env file to .env, set your photo and database folders and a database password, then run docker compose up -d. Open http://<server-ip>:2283 and create the admin account. Immich is not a backup on its own. The project tells you to follow a 3-2-1 backup plan and to back up your photo folder yourself. The current release is v3.2.2.

What Immich is

Immich is a self-hosted photo and video library with mobile apps that back up your phone’s camera roll to your own server. It’s open source under the GNU AGPL v3, and its documentation site lists FUTO as the company behind it. On September 26, 2026, the latest release on GitHub was v3.2.2, published September 15, 2026.

Immich’s install docs list several methods: Docker Compose, marked “[Recommended],” plus Kubernetes, Portainer, an experimental install script, and community-maintained guides for Unraid, TrueNAS and Synology. This guide follows the Docker Compose method, which the docs call “the recommended method to run Immich in production.”

Immich requirements

The details that trip people up, all from Immich’s requirements page:

• 4 GB of RAM can work only with machine learning features turned off.
• Older x86 CPUs. Since v3, the machine learning container on amd64 needs the x86-64-v2 instruction level. Immich says most CPUs released since about 2012 support it. In a VM, make sure the virtual CPU type exposes it.
• Database on local disk. The Postgres database, typically 1 to 3 GB, “should ideally use local SSD storage, and never a network share of any kind.”
• File system. Use a Unix-compatible file system such as EXT4, ZFS or APFS. Thumbnails and transcoded video add 10 to 20% to your library’s size on average.
• The command is docker compose, not the old docker-compose, which Immich says “is deprecated and is no longer supported.”

Windows, macOS, VMs and LXC

Immich says non-Linux operating systems “tend to provide a poor Docker experience and are strongly discouraged,” and its ability to help with them “will be severely reduced.” If you still want to try, it points Windows users to Docker Desktop or WSL 2, and Mac users to Docker Desktop. On Windows, the database folder can’t be on NTFS or exFAT, or on a Windows folder mounted into WSL. The docs show how to use a Docker volume instead.

Immich “runs well” in a full virtual machine. It does not recommend running Docker inside LXC containers. On Proxmox VE, that means a Linux VM rather than a container.

Install Immich with Docker Compose

Step 1: Get the two files

Create a folder and download the files from the latest GitHub release:

mkdir ./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

If you download them in a browser instead, rename example.env to .env.

For v3.2.2, GitHub lists these SHA-256 digests. They let you confirm the files came from the release unchanged:

Check with sha256sum docker-compose.yml before you edit anything. If a newer release is out, the latest links give you newer files with different hashes, which GitHub lists on that release’s page.

Step 2: Edit .env

The default file sets these values:

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
# TZ=Etc/UTC
IMMICH_VERSION=v3
DB_PASSWORD=postgres

• UPLOAD_LOCATION is where your photos and videos go. Immich says it should be a new directory with enough free space.
• DB_DATA_LOCATION is the database folder. Keep it on local SSD storage.
• DB_PASSWORD: change it. Use only the characters A-Za-z0-9, as the docs advise, to avoid parsing problems. The database isn’t exposed publicly, but a default password is still a bad idea.
• TZ: uncomment it and set your time zone.
• IMMICH_VERSION=v3 tracks the current major version. You can pin an exact version instead.

Step 3: Start Immich

docker compose up -d

If you get unknown shorthand flag: 'd' in -d or a permission error on the .env file, Immich says you’re probably using an old Docker package from your distribution. Replace it with Docker’s official Docker Engine packages. If Docker complains about healthcheck.start_interval, you need Docker Engine v25 or later, or you can comment out that line.

Step 4: Create the admin account

Open http://<server-ip>:2283. The first user to register becomes the admin, who can add other users.

Back up Immich properly

This is the part people skip, and Immich is direct about it. The project’s GitHub README says: “Always follow 3-2-1 backup plan for your precious photos and videos!”

Immich’s backup documentation adds three warnings:

• Immich prepares data but doesn’t back it up for you. “You still need to take care of using an actual backup tool to make a backup yourself.”
• The database matters. Immich stores file paths and metadata in the database and “does not scan the library folder, so database backups are essential.”
• Database backups don’t include your photos. Immich makes automatic database backups, by default daily at 2:00 AM, keeping the last 14, in UPLOAD_LOCATION/backups. The docs warn they “do not contain photos or videos — only metadata.”

So a complete backup is the whole UPLOAD_LOCATION folder, which includes the database dumps, copied to another disk and to another location. A 3-2-1 plan means three copies, on two types of storage, with one off site.

A phone that uploads to Immich doesn’t make Immich your backup. If the server’s disk fails and you’ve deleted photos from the phone, they’re gone.

Immich mobile apps

Immich’s quick-start guide lists these official sources:

• Immich on the Apple App Store
• Immich on Google Play
• APK files on Immich’s GitHub releases
• FUTO’s F-Droid repository, and Obtainium, using the config link from your server’s Utilities page

Sign in with your server address, http://<server-ip>:2283. To start backing up, tap the cloud icon, choose which albums to back up, and select Enable Backup. The first upload of a large library can take a long time.

Keep apps and server in step. Immich’s upgrade docs say the mobile app is usually compatible with the current and previous major version, but the server only works with its matching major version. Immich recommends updating the phone apps before upgrading the server.

Upgrading and reaching Immich away from home

Before every upgrade, read the release notes for breaking changes. Then run, in the folder with your compose file:

docker compose pull && docker compose up -d

Immich says breaking changes are meant to be limited to major versions. It doesn’t backport fixes, and “downgrading to an earlier version, even within the same minor version, is not supported.” That’s another reason to have a backup before you upgrade.

For access away from home, Immich’s FAQ recommends “the URL switching feature, a VPN, or a free trusted SSL certificate” over experimental options such as self-signed certificates. A mesh VPN is often the simplest route. See Tailscale vs WireGuard.

What Immich is not

• Not a backup. It’s a copy of your photos on one server. Back it up.
• Not a hosted service by default. You run the server, the updates and the storage.
• Not supported on every platform equally. Linux is recommended, and help for Windows and macOS is limited.
• Not something to buy from a reseller. Immich sells product keys itself and asks resellers not to present themselves as official.

If you’re choosing hardware for Immich, our TrueNAS vs Unraid comparison covers two NAS systems with community Immich guides. Official links and hashes are on our Immich app page.

Questions

Is Immich free?

Immich is open source under the GNU AGPL v3, and you can self-host it at no cost. Immich also sells product keys to support development.

How much RAM does Immich need?

At least 6 GB, with 8 GB recommended. With 4 GB it can run only with machine learning turned off.

Can I run Immich on Windows?

You can try, using Docker Desktop or WSL 2, but Immich strongly discourages non-Linux systems and offers limited help with them.

Can I run Immich on a Raspberry Pi?

Immich runs on arm64, so a 64-bit Raspberry Pi OS with enough RAM meets the architecture requirement. Check the 6 GB RAM minimum before you start.

What port does Immich use?

The web interface and mobile apps connect on port 2283.

Does Immich back up my photos automatically?

It backs up its database automatically, but not your photos and videos. You must back up UPLOAD_LOCATION yourself.

Can I run Immich in a Proxmox LXC container?

Immich doesn’t recommend Docker in LXC. Use a full VM.

How do I update Immich?

Read the release notes, then run docker compose pull && docker compose up -d. Update your phone apps first.

Can I downgrade Immich?

No. Immich says downgrading is not supported, even within the same minor version.

Where do I get the official Immich app?

From the Apple App Store, Google Play, Immich’s GitHub releases or FUTO’s F-Droid repository.

Sources

• Requirements, Immich docs, checked September 26, 2026
• Docker Compose [Recommended], Immich docs
• Quick start (mobile apps), Immich docs
• Backup and Restore, Immich docs
• Upgrading and versioning policy, Immich docs
• FAQ (remote access, resellers), Immich docs
• Immich README (3-2-1 warning), GitHub
• Immich v3.2.2 release (files and digests), GitHub