Immich

1. What is Immich?

Immich is software that lets you run your own photo and video library, like Google Photos or iCloud Photos, but on a computer you own (a desktop, an old laptop, a NAS or a mini server). Your phone backs up its photos to it automatically, and you browse them from the phone or a web browser, search by people, places and content ("beach", "cat"), build albums and share them with family.

It is free and open source (AGPL-3.0 license). Your photos live on your own drive and nobody bills you per gigabyte. In return, you are responsible for backups: if the drive dies and there is no copy, the photos are gone. The developers themselves warn you to follow the 3-2-1 rule (3 copies, 2 kinds of device, 1 copy off-site).

Immich was built for people comfortable running servers, so installation needs Docker (a tool that runs pre-packaged software). For a beginner, the first setup takes roughly 30–60 minutes.

A good fit if:

• You pay for Google Photos or iCloud storage and want to keep your photos on your own drive.
• You have a computer or NAS that can stay on, with disk space to spare.
• You are fine learning a few command-line steps and handling backups yourself.

Not a good fit if:

• You only need a few GB of photos. A free tier of an existing service is less work.
• You have no machine that can stay on, or you do not want to be responsible for your data.

2. What do you need?

According to the official documentation (docs.immich.app, Requirements page):

Item	Requirement
Operating system	Linux 64-bit recommended (Ubuntu, Debian…). Windows needs Docker Desktop or WSL 2, macOS needs Docker Desktop. Non-Linux systems are less recommended
RAM	Minimum 6 GB, recommended 8 GB. With machine learning turned off it can run on 4 GB
CPU	Minimum 2 cores, recommended 4; amd64 or arm64. Since v3, amd64 CPUs need the x86-64-v2 level (most CPUs since about 2012)
Storage	Enough room for your photos (thumbnails and transcoded video add about 10–20%). The database is about 1–3 GB and should sit on a local SSD, never on a network share
Software	Docker, including the docker compose command (Docker Engine v25 or newer)

No paid account and no API key is required.

Windows note: the docs state the database must not live on an NTFS or FAT32 drive, and you should not use WSL's /mnt folders. Beginners are better off on Linux (an old laptop running Ubuntu is the easiest option) or should follow the Windows section of the official docs closely.

Install Docker (pick one):

• Windows / macOS: download Docker Desktop from https://docs.docker.com/desktop/ and install it like any app.
• Ubuntu / Debian: follow https://docs.docker.com/engine/install/ .

3. Step-by-step install

The commands below come from the official install page (https://docs.immich.app/install/docker-compose). If you have never used a command line, see the "Never used a terminal?" box on the page.

Step 1: Create a folder and download two config files

Open Terminal (Linux/macOS) or PowerShell (Windows) and type, one at a time:

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 your machine says wget is missing (common on Windows and macOS), open the two addresses above in your browser instead and save the first as docker-compose.yml and the second as .env, both inside the immich-app folder.

What you should see: the immich-app folder contains docker-compose.yml and .env.

Step 2: Edit the .env file

Open .env in a text editor and change three things:

• UPLOAD_LOCATION: the folder where your photos and videos will be stored. Pick a drive with plenty of free space.
• DB_PASSWORD: change the database password from the default postgres. Use letters and digits only (A–Z, a–z, 0–9).
• TZ: remove the # at the start of the line and set your time zone, for example Asia/Ho_Chi_Minh.

Save the file.

Step 3: Start it

Inside the immich-app folder, type:

docker compose up -d

The first run downloads the components, which takes a few minutes depending on your connection. Type docker compose (with a space), not docker-compose: the old form is not supported.

What you should see: status lines saying the components started (Started/Healthy), then the prompt returns.

4. First use

1. Open a browser and go to http://<your machine's IP address>:2283 (on the machine itself you can use http://localhost:2283). The port is 2283.
2. Click Getting Started and create an account. The first person to register becomes the administrator.
3. Install the Immich app on your phone (Google Play, App Store; other sources are listed at https://docs.immich.app/install/post-install ).
4. Open the app, enter http://<your machine's IP address>:2283 as the server address and sign in with the account you just made. The phone must be on the same Wi-Fi as the machine running Immich.
5. Open the app's backup screen, choose the albums to back up and turn backup on. Your photos start moving to your own library.

To add family members: as administrator go to Administration > Users and click Create user.

Note: an address like 192.168.x.x only works at home. Viewing photos while away needs extra remote-access setup, which is considerably more involved; read the official docs before exposing the machine to the Internet.

5. Common problems and fixes

Symptom	Cause	Fix
docker: command not found or docker compose not recognised	Docker missing or too old	Install Docker per section 2; use docker compose (with a space), Docker Engine v25 or newer
Browser cannot reach :2283	Containers still starting, wrong IP, firewall	Run docker compose ps to see whether containers are up, re-check the machine's IP, open port 2283
Database error or permission denied at startup	Database on a network share, NTFS/FAT32, or a folder with wrong permissions	Put data on a local drive with a Linux-style filesystem (ext4…), as the Requirements page says
Machine slow, freezing, containers stopping	Not enough RAM (under 6 GB)	Close other apps, or turn off machine learning per the docs to run on 4 GB
Phone cannot connect to the server	Different Wi-Fi, missing http:// or :2283	Put the phone on the same Wi-Fi and enter the full http://IP:2283

6. Uninstall / update

Update. Before updating, read the release notes of the new version (https://github.com/immich-app/immich/releases) because breaking changes can happen, and back up the database. Update the phone app first, then the server. In the immich-app folder run:

docker compose pull && docker compose up -d

To clean up old images and save disk space:

docker image prune

Immich does not support downgrading, even within the same minor version.

Uninstall. In the immich-app folder run docker compose down to stop and remove the containers. Your photos remain in the UPLOAD_LOCATION folder and the database files in the location set in .env. Delete those two places only after you have copied your photos somewhere else.

7. FAQ

Does it cost money? The software is free. You pay only for the machine, the drives and electricity.

Will it run on a weak machine? Minimum 2 CPU cores and 6 GB RAM; a 4 GB machine only works with machine learning turned off.

Do I need internet? Yes, to download at install time and for updates. At home the phone just needs the same Wi-Fi as the server.

Can I try it first? There is a demo at https://demo.immich.app (the demo login is in the official README), handy for seeing the interface before you invest the effort.

Where do my photos live? On the drive of the machine you set up, in the UPLOAD_LOCATION folder. That is why backups are your job.