> ## Documentation Index
> Fetch the complete documentation index at: https://help.freakhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Install Immich with Docker on a VPS

> Install Immich with Docker on a VPS: download the official docker-compose.yml and .env, set UPLOAD_LOCATION and DB_PASSWORD, start it and serve it over HTTPS.

To install Immich with Docker on a VPS, download the official `docker-compose.yml` and `example.env` (saved as `.env`) from Immich's latest release, set `UPLOAD_LOCATION`, `DB_PASSWORD` and `TZ`, then run `sudo docker compose up -d`. Serve port 2283 through Nginx with HTTPS and register the first user, who becomes the admin. Immich needs at least 6 GB RAM.

| Difficulty | Time | Works on | Needs |
| - | - | - | - |
| Intermediate | 30 minutes | Ubuntu 22.04 / 24.04, Debian 12 / 13, AlmaLinux / Rocky 9 / 10 (amd64 or arm64) | [Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md) with Compose, 6 GB+ RAM, a domain |

## What is Immich?

Immich is a self-hosted photo and video library, similar to Google Photos. Its mobile apps back up your camera roll to your server, and the web app adds timelines, albums, sharing, face recognition and smart search.

## What are Immich's requirements?

From the [official requirements](https://docs.immich.app/install/requirements):

| Resource | Minimum | Recommended | Notes |
| - | - | - | - |
| RAM | 6 GB | 8 GB | With 4 GB, Immich can run with machine learning disabled |
| CPU | 2 cores | 4 cores | amd64 or arm64; since v3 the machine learning container on amd64 needs the x86-64-v2 level |
| Storage | Your library + 10–20% | SSD for the database | Thumbnails and transcoded videos add about 10–20%; the Postgres database is typically 1–3 GB |

Machine learning (smart search, face detection) and video transcoding are the most CPU-heavy jobs, especially during the first upload of a large library. On a VPS they run on the CPU. Immich's FAQ warns that 2 or 3 concurrent machine learning jobs can probably max out the CPU of a normal machine.

## Before you start

* Install Docker Engine with the Compose plugin from Docker's repository: [install Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md). Immich needs `docker compose`; the old `docker-compose` and the `docker.io` package on Ubuntu 22.04 cause errors.
* Point `photos.example.com` at your server. See [point a domain to your server](https://help.freakhosting.com/portals/other/how-to-point-a-domain-to-your-server.md).
* Plan disk space. To keep photos on a second disk, [mount it](https://help.freakhosting.com/portals/other/how-to-mount-a-new-disk-on-linux.md) first. Keep the database on local storage, never a network share.
* The commands use `sudo`; leave it out if you are `root`.

## How to install Immich with Docker Compose

**1. Download the official files**

```bash theme={null}
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
```

Always use the files from the latest release, not from the `main` branch.

**2. Edit .env**

Open it with `nano .env` and set:

```ini theme={null}
UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
TZ=Europe/London
IMMICH_VERSION=v3
DB_PASSWORD=ChangeThisToALongRandomString
```

Uncomment the `TZ` line. Use only letters and numbers in `DB_PASSWORD`; generate one with `openssl rand -hex 24`. `IMMICH_VERSION=v3` follows the current major version, as the release file sets it. Point `UPLOAD_LOCATION` at a folder with enough space, for example `/mnt/photos/immich`.

**3. Keep port 2283 private**

The official file publishes Immich on all addresses. Bind it to `127.0.0.1` so only Nginx can reach it:

```bash theme={null}
sed -i "s/- '2283:2283'/- '127.0.0.1:2283:2283'/" docker-compose.yml
grep 2283 docker-compose.yml
```

The output shows `- '127.0.0.1:2283:2283'`.

**4. Start Immich**

```bash theme={null}
sudo docker compose up -d
```

This starts four containers: `immich_server`, `immich_machine_learning`, `immich_redis` and `immich_postgres`.

## How to serve Immich over HTTPS with Nginx

**1. Create the Nginx site**

Create `/etc/nginx/sites-available/photos.example.com` (Ubuntu / Debian) or `/etc/nginx/conf.d/photos.example.com.conf` (AlmaLinux / Rocky). This follows the [Immich reverse proxy example](https://docs.immich.app/administration/reverse-proxy):

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name photos.example.com;

    client_max_body_size 50000M;
    proxy_request_buffering off;
    client_body_buffer_size 1024k;

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_redirect     off;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout       600s;

    location / {
        proxy_pass http://127.0.0.1:2283;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

Immich must be served at the root of a (sub)domain, not a path such as `/immich`.

**2. Enable, test and get a certificate**

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/photos.example.com /etc/nginx/sites-enabled/   # Ubuntu / Debian only
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d photos.example.com
```

On AlmaLinux / Rocky, run `sudo setsebool -P httpd_can_network_connect 1` before testing.

## How to create the admin user

Open `https://photos.example.com` and click **Getting Started**. The first user to register becomes the admin and can add other users. Then install the Immich mobile app, log in with `https://photos.example.com` as the server URL and turn on backup.

> [!WARNING]
>
> Register the admin straight after the site goes live. Until then, whoever opens the page first becomes the admin.

## How to check it worked

```bash theme={null}
sudo docker compose ps
```

All four containers show `Up` and `(healthy)` after a minute or two. Upload a photo; it appears in the timeline, and **Administration > Job Queues** shows thumbnail and machine learning jobs running.

## How to back up Immich

Immich automatically dumps its database every day at 2:00 and keeps the last 14 dumps in `UPLOAD_LOCATION/backups`. Change this under **Administration > Settings > Database Dump Settings**. The dumps hold only metadata, not photos, so back up the **whole `UPLOAD_LOCATION` folder**, which includes the photos and the `backups` folder:

```bash theme={null}
sudo rsync -a ~/immich-app/library/ alex@198.51.100.20:/backups/immich/
```

See [back up files with rsync](https://help.freakhosting.com/portals/other/how-to-back-up-files-with-rsync.md) and the [Immich backup guide](https://docs.immich.app/administration/backup-and-restore).

## How to update Immich

Read the [release notes](https://github.com/immich-app/immich/releases) for breaking changes first. Update the mobile apps before the server: the server only works with apps from the same major version.

```bash theme={null}
cd ~/immich-app
sudo docker compose pull && sudo docker compose up -d
sudo docker image prune
```

For a new major version, change `IMMICH_VERSION` in `.env` and download the new release's `docker-compose.yml` first. Immich does not support downgrading.

## Frequently asked questions

### Can I run Immich on a 4 GB VPS?

Immich says 4 GB can work with machine learning disabled. Turn it off under **Administration > Settings > Machine Learning Settings**, and comment out the `immich-machine-learning` service in `docker-compose.yml` so it doesn't start. Search and the **Explore** page then work poorly.

### How do I lower CPU use during the first upload?

Set job concurrency for transcoding and machine learning jobs to 1, set **Settings > Transcoding Settings > Threads** to 1 or 2, and consider the smaller `buffalo_s` facial recognition model.

### Does Immich need a GPU?

No. Everything runs on the CPU by default. Hardware acceleration is optional and only works if the server exposes a supported GPU to Docker.

### Why does the machine learning container crash with SIGILL or code 132?

The CPU lacks a required instruction set. On amd64, Immich v3's machine learning container needs the x86-64-v2 level.

## Related guides

> [card] [VPS and dedicated server guides](https://help.freakhosting.com/portals/other/vps-and-dedicated-server-guides.md)
>
> Every guide in this section.

> [card] [Self-host Nextcloud](https://help.freakhosting.com/portals/other/how-to-self-host-nextcloud.md)
>
> Files, calendar and contacts.

> [card] [Mount a new disk](https://help.freakhosting.com/portals/other/how-to-mount-a-new-disk-on-linux.md)
>
> Room for a large photo library.

> [card] [Check memory usage](https://help.freakhosting.com/portals/other/how-to-check-memory-usage-on-linux.md)
>
> See if Immich has enough RAM.

> [card] [Schedule and restore VPS backups](https://help.freakhosting.com/portals/vps-panel/how-to-schedule-and-restore-backups.md)
>
> Panel backups for your VPS.

***

> [!NOTE]
>
> **Checked against the official [Immich documentation](https://docs.immich.app/install/docker-compose)** and the latest release's `docker-compose.yml` and `example.env` on 4 November 2026 (`IMMICH_VERSION=v3`); `docker-compose.yml` validated with `docker compose config` and the Nginx configuration syntax-tested on Ubuntu 24.04 LTS. Requirements and settings can change between Immich releases.

> [!NOTE]
>
> ### Need Extra Help?
>
> If you encounter any issues, our support team is ready to assist:
>
> * **Live Chat:** Quick assistance via our website.
> * **Support Ticket:** [Open a Ticket](https://freakhosting.com/clientarea/submitticket.php)
> * **Discord:** [Join our Community](https://discord.gg/freakhosting)
> * **Email:** [support@freakhosting.com](mailto:support@freakhosting.com)

> [!TIP]
>
> ### Save on Your Hosting
>
> Ready to upgrade your hosting? Use code **KB20** at checkout for **20% off** your first order!

***

**Last Updated:** November 2026


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.