Home

Installation

Get Noodle Gallery running with Docker Compose in under five minutes. An existing Immich setup carries over: you swap two image names.

Looking for in-depth guides? Read the full documentation

Migrating from upstream Immich

Already running Immich? Swap two image names in your docker-compose.yml and bump IMMICH_VERSION in your .env. Three lines. The current version is v5.

Back up your database first: docker exec -t immich_postgres pg_dumpall -U postgres > backup.sql
docker-compose.yml
-image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
+image: ghcr.io/open-noodle/gallery-server:${IMMICH_VERSION:-release}
-image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
+image: ghcr.io/open-noodle/gallery-ml:${IMMICH_VERSION:-release}
.env
-IMMICH_VERSION=v3
+IMMICH_VERSION=v5

Then pull the new images and restart:

docker compose pull && docker compose up -d

Your data, database and configuration stay compatible. There are no migration steps.

Changed your mind? Swap back in one script.

Gallery ships a cleanup SQL that drops every Gallery-specific table, column and migration record: Shared Spaces, pet detection, classifications, duplicate data. What is left is a plain upstream Immich database. Your photos and videos are never touched. Flip the two image names back and you're on upstream.

Read the switch-back guide

Wondering what Gallery actually adds on top of Immich? Read the full Gallery vs Immich comparison →

Starting fresh?
0

Requirements

Hardware2+ CPU cores, 4 GB RAM, or 6 GB+ for machine learning
DockerDocker Engine v25+ with docker compose (v2 plugin)
StorageLocal disk or S3-compatible storage, plus ~10 GB for containers and database
OSLinux (recommended), macOS, or Windows with WSL2
1

Download the configuration files

Create a directory, then download the Docker Compose file and the environment template.

Terminal
mkdir ./noodle-gallery
cd ./noodle-gallery

wget -O docker-compose.yml https://github.com/open-noodle/gallery/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/open-noodle/gallery/releases/latest/download/example.env
You can also download these files manually from the latest release page. Rename example.env to .env.
2

Configure environment

Open .env and set your paths and password. The options you have to touch sit at the top; the S3 block is optional.

.env
# ── Core Settings ──────────────────────────────────────────────

# Where your photos and videos are stored
UPLOAD_LOCATION=./library

# Where PostgreSQL stores its data (must be local disk, not a network share)
DB_DATA_LOCATION=./postgres

# Timezone: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Etc/UTC

# Container image tag: "release" for latest, "v5" for latest v5.x, or pin e.g. "v5.0.0"
IMMICH_VERSION=release

# IMPORTANT: change this to a random password (A-Za-z0-9 only)
DB_PASSWORD=change-me-to-something-random

# These defaults rarely need changing
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

# ── S3-Compatible Storage (optional) ──────────────────────────
# Uncomment to store uploads in S3 instead of local disk.
# Works with AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, etc.

# IMMICH_STORAGE_BACKEND=s3
# IMMICH_S3_BUCKET=my-gallery-bucket
# IMMICH_S3_REGION=us-east-1
# IMMICH_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
# IMMICH_S3_ACCESS_KEY_ID=
# IMMICH_S3_SECRET_ACCESS_KEY=
# IMMICH_S3_SERVE_MODE=redirect
# IMMICH_S3_PRESIGNED_URL_EXPIRY=3600

Variable reference

UPLOAD_LOCATIONPath for uploaded media. Use an absolute path in production.
DB_DATA_LOCATIONPath for PostgreSQL data. Must be a local disk. Network shares are not supported.
DB_PASSWORDDatabase password. Only A-Za-z0-9 characters. Change before first run.
IMMICH_VERSIONContainer tag. release = latest, v5 = latest v5.x, or pin to a specific version.
IMMICH_STORAGE_BACKENDSet to s3 to store new uploads in S3. Default: disk. Existing disk files continue working.
IMMICH_S3_BUCKETS3 bucket name. Required when using S3 storage.
IMMICH_S3_ENDPOINTCustom endpoint for non-AWS services (MinIO, R2, B2). Omit for AWS S3.
IMMICH_S3_SERVE_MODEredirect returns presigned URLs (faster). proxy streams through the server. Default: redirect.
3

Start the containers

From your noodle-gallery directory, run:

Terminal
docker compose up -d

This pulls the images, creates the database and starts the services. The first run downloads ~2 GB, so give it a few minutes.

Use docker compose (with a space), not docker-compose (with a hyphen). The standalone docker-compose binary is deprecated.
4

Access the web UI

Open http://your-server-ip:2283. Gallery asks you to create the first admin account.

Default URLhttp://localhost:2283

The mobile app (Android & iOS) connects to the same URL. Download it from thePlay Store orApp Store and point it to your server.

GPU acceleration optional

To run face detection, CLIP and pet detection on a GPU instead of the CPU, switch the machine learning image:

# In docker-compose.yml, change the ML image tag:
image: ghcr.io/open-noodle/gallery-ml:${IMMICH_VERSION:-release}-cuda

Available tags: -cuda (NVIDIA), -rocm (AMD), -openvino (Intel).

Upgrading

To update to the latest version:

Terminal
docker compose pull
docker compose up -d

Database migrations run on startup. Back up your database before a major version upgrade.

API documentation

Gallery has a REST API described by OpenAPI. Every running instance serves Swagger UI at /doc, fork-specific endpoints included: Shared Spaces, user groups, pet detection.

Your instancehttp://your-server:2283/doc

You can also browse the API on the live demo:

Browse API on demo.opennoodle.de

Frequently asked questions

How do I migrate from upstream Immich to Noodle Gallery?

Swap two image names in your docker-compose.yml: replace ghcr.io/immich-app/immich-server with ghcr.io/open-noodle/gallery-server, and ghcr.io/immich-app/immich-machine-learning with ghcr.io/open-noodle/gallery-ml. Then run 'docker compose pull && docker compose up -d'. Your data, database and configuration stay compatible, so there are no migration steps. Back up your database first with pg_dumpall.

Can I import my photos from Google Photos?

Yes. Noodle Gallery has an import wizard that reads your Google Takeout archive in the browser. Dates, GPS coordinates, descriptions, favorites and album structure all survive the move. Upload the zip and the wizard handles the rest.

What are the system requirements?

2+ CPU cores and 4 GB RAM, or 6 GB+ for the machine learning features. Docker Engine v25+ with the docker compose v2 plugin. Local disk or S3-compatible storage for the library, plus ~10 GB for containers and database. Linux is recommended; macOS and Windows (with WSL2) work too.

Does Noodle Gallery support GPU acceleration?

Yes. Use a GPU-accelerated machine-learning image: -cuda for NVIDIA, -rocm for AMD, or -openvino for Intel. Change the gallery-ml image tag in docker-compose.yml from 'release' to 'release-cuda' (or your vendor's tag) and restart the stack.

Can I store my photos in S3-compatible storage?

Yes. Any S3-compatible backend works: AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi. Set IMMICH_STORAGE_BACKEND=s3 in your .env file, along with the bucket, region, endpoint and credentials.

Is Noodle Gallery free?

Yes. Noodle Gallery is free and open source under AGPL-3.0. Self-host it on hardware you own. There is no subscription and no storage cap.

How do I upgrade Noodle Gallery to the latest version?

Run 'docker compose pull && docker compose up -d' from your noodle-gallery directory. Database migrations run on startup. Back up your database before a major version upgrade.

Need help?

Check the official documentation, browse the API reference, ask on Discord, or open an issue on GitHub.