Installation
Get Noodle Gallery running with Docker Compose in under five minutes. Compatible with any existing Immich setup.
Looking for in-depth guides? Read the full documentationMigrating from upstream Immich
Already running Immich? Switching is easy — swap two image names in your docker-compose.yml and bump IMMICH_VERSION in your .env.
The current version is v4.
docker exec -t immich_postgres pg_dumpall -U postgres > backup.sql 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} IMMICH_VERSION=v2 IMMICH_VERSION=v4 Then pull the new images and restart:
docker compose pull && docker compose up -dYour data, database, and configuration are fully compatible — no migration steps needed.
Gallery ships a cleanup SQL that drops every Gallery-specific table, column, and migration record — shared spaces, pet detection, classifications, duplicate data — leaving 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 guideWondering what Gallery actually adds on top of Immich? Read the full Gallery vs Immich comparison →
Requirements
docker compose (v2 plugin) Download the configuration files
Create a directory for Noodle Gallery and download the Docker Compose file and environment template.
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.envexample.env to .env. Configure environment
Open the .env file and configure your settings. The essential options are at the top — S3 storage is optional.
# ── 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, "v4" for latest v4.x, or pin e.g. "v4.0.1"
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=3600Variable reference
UPLOAD_LOCATION Path for uploaded media. Use an absolute path in production. DB_DATA_LOCATION Path for PostgreSQL data. Must be a local disk — network shares are not supported. DB_PASSWORD Database password. Only A-Za-z0-9 characters. Change before first run. IMMICH_VERSION Container tag. release = latest, v4 = latest v4.x, or pin to a specific version. IMMICH_STORAGE_BACKEND Set to s3 to store new uploads in S3. Default: disk. Existing disk files continue working. IMMICH_S3_BUCKET S3 bucket name. Required when using S3 storage. IMMICH_S3_ENDPOINT Custom endpoint for non-AWS services (MinIO, R2, B2). Omit for AWS S3. IMMICH_S3_SERVE_MODE redirect returns presigned URLs (faster). proxy streams through the server. Default: redirect. Start the containers
From your noodle-gallery directory, run:
docker compose up -dThis pulls the container images, creates the database, and starts all services. The first run downloads ~2 GB of images and may take a few minutes.
docker compose (with a space), not docker-compose (with a hyphen). The standalone docker-compose binary is deprecated. Access the web UI
Open http://your-server-ip:2283 in your browser. You'll be prompted to create the first admin account.
http://localhost:2283 The mobile app (Android & iOS) connects to the same URL. Download it from the Play Store or App Store and point it to your server.
GPU acceleration optional
For faster machine learning inference (face detection, CLIP, pet detection), use a GPU-accelerated ML 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:
docker compose pull
docker compose up -dDatabase migrations run automatically on startup. Always back up your database before major version upgrades.
API documentation
Gallery exposes a full REST API documented via OpenAPI. Every running instance serves interactive Swagger UI at /doc, including all fork-specific endpoints for Shared Spaces, User Groups, and Pet Detection.
http://your-server:2283/doc You can also browse the API on the live demo:
Browse API on demo.opennoodle.deFrequently 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 are fully compatible — no migration steps required. Always back up your database first with pg_dumpall.
Can I import my photos from Google Photos?
Yes. Noodle Gallery has a built-in import wizard that reads your Google Takeout archive directly in the browser. Dates, GPS coordinates, descriptions, favorites, and album structure are all preserved. No scripts or CLI required — just upload the zip.
What are the system requirements?
2+ CPU cores, 4 GB RAM minimum (6 GB+ recommended for machine learning features), Docker Engine v25+ with the docker compose v2 plugin, plus local disk or S3-compatible storage for your library and ~10 GB for containers and database. Linux is recommended; macOS and Windows (with WSL2) also work.
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. Noodle Gallery supports any S3-compatible backend including AWS S3, MinIO, Cloudflare R2, Backblaze B2, and Wasabi. Set IMMICH_STORAGE_BACKEND=s3 along with the bucket, region, endpoint, and credentials in your .env file.
Is Noodle Gallery free?
Yes. Noodle Gallery is free and open source under AGPL-3.0. You can self-host on any hardware you own with no subscription, no storage limits, and no usage fees.
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 automatically on startup. Always back up your database before major version upgrades.