Immich: Overview, Core Features, and Getting Started Guide

What it is

According to the project README on GitHub, Immich is a high performance self-hosted photo and video management solution. In digital technology, self-hosting refers to installing and operating software on your own private hardware or local home server, rather than delegating data storage to commercial cloud service providers. Immich provides users with direct custody over their digital media by combining a central server application with dedicated clients built for web browsers and mobile devices.

The application is published as open source under the terms of the GNU AGPL v3 (GNU Affero General Public License version 3). The project maintains a community presence on Discord, and its user interface and documentation are supported by community translations across dozens of global languages, including Spanish, French, German, Japanese, Chinese, and many others.

For people who wish to inspect the interface and test its workflows without setting up local infrastructure first, the project hosts a public demonstration instance at demo.immich.app. This online demo can be accessed directly inside a web browser or connected to the mobile application using the demo endpoint URL, signing in with the provided email address [email protected] and the password demo.

A core operational recommendation highlighted throughout the project repository and documentation is data safety. The project documentation advises users to follow the established 3-2-1 backup strategy. In data protection terminology, this guideline means preserving three separate copies of media on two different storage formats, with at least one copy held in an off-site location to ensure precious photos and videos remain secure.

What it can do

Immich incorporates a broad feature set designed to handle photo and video ingestion, catalog organization, multi-user administration, and media discovery across web and mobile platforms.

Media Ingestion and Backups

Immich enables users to upload, view, and download both photos and video files. The software includes built-in duplicate asset prevention to avoid storing identical files multiple times. On mobile operating systems, the application supports background backups as well as automated syncing that triggers whenever the application is opened. Mobile users can also select specific albums to back up rather than uploading their entire local camera roll.

Beyond standard media files, Immich supports professional camera RAW formats, motion photos, and Apple Live Photos, allowing users to back up and play back dynamic media. On the web dashboard, the system can display 360-degree panoramic images.

Organization and Sharing

The platform provides multiple organization views, including standard albums, shared albums, and partner sharing, which allows designated accounts to view each other’s libraries. Users can share items externally by generating public sharing links. Inside the library, assets can be archived, organized into custom folder views, grouped using user-defined storage directory structures, or marked as favorites. The web application also supports applying custom tags to assets.

For rapid navigation through extensive photo timelines, Immich uses virtual scrolling alongside a draggable, scrubbable scrollbar. The interface also supports photo stacking, which groups together related or burst shots into a single organized thumbnail, and offers a read-only gallery mode when editing capabilities should be restricted.

Search and Machine Learning

Immich incorporates automated machine learning tools to index and find media without manual tagging. The system features facial recognition and clustering to group portraits of the same person together. It also provides automated object recognition and integrates CLIP (Contrastive Language-Image Pre-training) models, allowing users to run natural language search queries based on scene descriptions or objects.

In addition to visual recognition models, the application supports searching by EXIF camera metadata (such as exposure settings or camera models) and geographical coordinates. Assets containing location data can be explored visually through an integrated global map view. The platform also includes a “Memories” feature that resurfaces photos and videos taken on the same date in past years.

Access Control and Multi-User Management

Immich is designed with a native multi-user architecture, enabling several individuals to maintain independent media libraries on a single server installation. Administrative tasks and account creation are managed through an administrative panel on the web client. For security and automation, Immich supports OAuth authentication protocols as well as API key generation for automated integrations. When mobile devices lose active internet connectivity, the mobile client provides offline support so users can continue viewing previously cached local galleries.

How to get started

The official Immich documentation outlines a quick start deployment path using Docker and Docker Compose. Docker is an application container platform that bundles services, databases, and dependencies into reproducible environments.

Step 1: Download the Configuration Files

To begin, create a dedicated directory on your host server to store the setup files and enter that directory:

mkdir ./immich-app
cd ./immich-app

Download the official Docker Compose deployment file and the template environment configuration file by running the following commands:

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

Alternatively, both files can be downloaded directly through a standard desktop web browser and transferred to the chosen directory. When downloading via a browser, ensure the template file example.env is renamed to .env.

Step 2: Populate the Environment Variables

Open the .env file in a text editor to set your desired local configuration values:

• UPLOAD_LOCATION: Define the local path where your uploaded media files and backups will be stored (the default value is ./library). This should point to a location on the server with sufficient free storage capacity.
• DB_DATA_LOCATION: Designate the storage directory for the PostgreSQL database files (defaulting to ./postgres). Note that network file shares are not supported for database storage.
• TZ: Set your local time zone by uncommenting the timezone line and supplying a valid identifier (such as Etc/UTC).
• IMMICH_VERSION: Sets the software release version (such as v3 or pinned specific releases like v2.1.0).
• DB_PASSWORD: Set a secure connection password for the local PostgreSQL database service. The documentation notes that this password is only used for local authentication and recommends using only alphanumeric characters (A-Za-z0-9) without special symbols or spaces to avoid parsing errors. Tools such as pwgen can help generate suitable passwords.
• DB_USERNAME and DB_DATABASE_NAME: Standard default database identifiers (postgres and immich) do not require modification under standard deployments.

Step 3: Start the Server Containers

From the directory containing your customized docker-compose.yml and .env files, run the following command to launch the Immich services in the background:

docker compose up -d

Step 4: Access the Web Dashboard

After the containers initialize, open a web browser and navigate to http://<machine-ip-address>:2283. The first account registered on the server will automatically receive administrative privileges. Click the “Getting Started” button, complete the registration steps, and log in to the dashboard. You can test basic functionality by uploading an initial photo through the web interface.

Step 5: Install and Link the Mobile Application

The Immich mobile app can be downloaded through several distribution channels: the Apple App Store, Google Play Store, direct APK files on GitHub Releases, Obtainium (using the configuration link found on the server’s Utilities page), and FUTO F-Droid.

To connect your mobile device:

1. Open the mobile application and set the Server Endpoint URL to http://<machine-ip-address>:2283.
2. Sign in with your registered account credentials. Photos previously uploaded through the web UI will become visible on the mobile screen.
3. Tap the cloud icon in the upper right corner to reach the backup menu.
4. Select the specific photo albums you wish to sync to your Immich server.
5. Scroll down and press “Enable Backup” to begin uploading assets.
6. The Job Queues tab on the server allows administrators to observe media processing and background tasks.

Step 6: Maintain Independent Backups

Immich includes built-in database backup routines. However, the database only stores system metadata and user records. The documentation emphasizes that administrators must independently establish manual backup routines for all original photos and videos stored inside the UPLOAD_LOCATION folder.

To expand an existing library, users can connect an External Library, import standalone media archives, or utilize the immich-go utility to import collections exported from Google Takeout.

Pricing and requirements

System Requirements

According to the official quick start documentation, deploying Immich requires:

• A host system equipped with Docker.
• A minimum hardware specification of at least 6GB of RAM and 2 CPU cores.
• Local storage drives for the database directory (DB_DATA_LOCATION), as network shares are not supported for hosting the PostgreSQL database.
• Adequate free disk storage capacity at the designated UPLOAD_LOCATION path to accommodate media files.

Pricing and Licensing

Immich is distributed as open-source software under the GNU AGPL v3 license. Specific pricing details, licensing options, and project contribution tiers are subject to the project’s official website at immich.app.

Who it is for

Immich is designed for individuals, families, and self-hosting enthusiasts who want to maintain direct ownership and control over their personal photos and videos. It is well suited for users seeking an alternative to commercial cloud platforms that centralize media on third-party servers.

Because the system includes multi-user support, shared albums, and partner sharing, it works well for households that want to back up media from multiple family members onto a shared local server while keeping individual libraries separated. It also suits photographers who capture images in RAW format, live photos, or 360-degree panoramic formats. Furthermore, users interested in machine learning capabilities—such as automated face clustering, object identification, and natural language search—can run these workloads on their own hardware, provided their systems meet the baseline multi-core CPU and memory requirements.

Alternatives

PhotoPrism is an alternative open-source photo management solution. Ente is another alternative application designed for managing and backing up photos.

Sources

• https://github.com/immich-app/immich
• https://immich.app/docs/overview/introduction
• https://github.com/photoprism/photoprism
• https://github.com/ente-io/ente