What Is Immich? A Complete Guide to Self-Hosted Photo Management

What Is Immich? A Complete Guide to Self-Hosted Photo Management

In an era where digital photos accumulate by the thousands, managing a personal library has become a significant challenge. Cloud services like Google Photos and Apple iCloud offer convenience but often come with subscription costs, privacy concerns, and the risk of vendor lock-in. Enter Immich: an open-source, self-hosted photo and video management solution designed to replicate—and in many areas surpass—the functionality of mainstream cloud platforms. This guide provides a comprehensive, technically detailed exploration of Immich, covering its architecture, features, deployment, and unique value proposition.

Core Architecture and Self-Hosted Foundation

Immich is built on a client-server model. The server component runs on your own hardware—whether a dedicated home server, a Raspberry Pi, a NAS device, or a cloud VPS—while clients include a web interface, mobile apps (iOS and Android), and a command-line tool. The backend is powered by Node.js, with a React-based frontend for the web UI and Flutter for mobile applications. Data storage relies on PostgreSQL for metadata and asset indexing, while Redis serves as a caching layer for performance and task queuing. Actual image and video files are stored on your chosen local or network-attached storage.

Key Features That Rival Google Photos

Immich’s primary strength lies in its feature parity with major cloud services, but with full data ownership. Below is a breakdown of its core capabilities.

Automatic Backup and Synchronization
The mobile app provides background backup, uploading photos and videos as they are taken. Unlike Google Photos, which compresses files on free tiers, Immich preserves original quality. Users can configure selective album backups, Wi-Fi-only uploads, and retention policies. The server detects duplicates and handles incremental sync efficiently.

Machine Learning and Smart Search
Immich integrates machine learning models for automatic tagging, object detection, and facial recognition. The system uses TensorFlow-based models to analyze image content—identifying objects like “cat,” “sunset,” or “car”—and indexes faces across your library. This enables natural language search (e.g., “find photos of Sarah at the beach”) without manual tagging. All processing occurs locally on your server; no data is sent to external services.

Timeline and Map Views
Assets are organized chronologically in a scrollable timeline, similar to Google Photos. A map view uses embedded EXIF geolocation data (or user-assigned locations) to plot photos on an interactive OpenStreetMap. Users can filter by date range, file type, or location cluster.

Album Sharing and Collaborative Features
Immich supports both personal and shared albums. You can create a shared link with optional expiration dates and password protection. Collaborators with the link can upload their own photos to the album, making it ideal for event collections or family archives. Shared albums preserve original resolution and metadata.

Library Management and Tagging
Beyond automatic ML tags, users can assign manual labels, star favorites, and archive hidden folders. The system supports nested folders, but Immich abstracts physical file structure—assets are indexed by database, not directory hierarchy. This allows renaming or reorganizing files on disk without breaking references.

Video Support
Video playback includes codec support for H.264, H.265, VP9, and AV1. Immich transcodes videos on-the-fly for browser compatibility, but retains original files. Mobile apps can stream or download full-resolution clips.

Hardware Acceleration and Performance

Optimizing performance on home hardware is critical. Immich supports hardware transcoding via VA-API (Intel), NVENC (Nvidia), and VideoToolbox (Apple). For ML tasks, it can leverage GPU acceleration (CUDA) or run purely on CPU. A modern quad-core processor with 8GB RAM is sufficient for a library of 50,000–100,000 assets, but larger collections benefit from more memory and a dedicated GPU.

Deployment Options and System Requirements

Immich is deployed via Docker Compose, making it accessible to users with basic Linux or Docker experience. The official repository includes a docker-compose.yml file with services for the server, web frontend, microservices (for background ML tasks), Redis, and PostgreSQL.

Minimum Hardware Requirements:

• 2 CPU cores (4+ recommended)
• 4GB RAM (8GB+ for ML features)
• 50GB+ storage (scales with library)
• 64-bit Linux OS (Ubuntu/Debian/Fedora) or macOS

Step-by-Step Deployment Overview:

1. Install Docker and Docker Compose on your server.
2. Clone the Immich repository: git clone https://github.com/immich-app/immich.git
3. Copy example.env to .env and configure paths for UPLOAD_LOCATION and DB_PASSWORD.
4. Run docker-compose up -d to start all services.
5. Access the web interface at http://:2283. Create the admin account via the initial setup wizard.

Alternative Deployment Methods:

• Unraid: Available via Community Applications.
• TrueNAS Scale: Official App from the catalog.
• Synology/DSM: Manual Docker install via Container Manager.
• Kubernetes: Community Helm charts exist but are less mature.

Privacy and Data Sovereignty

Immich’s self-hosted nature guarantees that your photos never leave your network unless you explicitly share them. There are no telemetry, analytics, or cloud dependencies. The ML models run locally; external API calls are disabled by default. Encryption at rest is achieved via filesystem-level encryption (e.g., LUKS, ZFS encryption) rather than application-layer encryption, as Immich must read files to serve thumbnails and metadata.

Comparison to Alternatives (Nextcloud, PhotoPrism, LibrePhotos)

Feature	Immich	Nextcloud Photos	PhotoPrism	LibrePhotos
Mobile backup	Automatic, background	Manual or scheduled	Via WebDAV	Manual
ML object/face detection	Built-in (local)	Add-on (via Recognize)	Built-in (local)	Built-in (local)
Video transcoding	Yes	Limited	Yes	No
Map view	OpenStreetMap	OSM integration	OSM with geocoding	OSM
User interface	Modern, mobile-first	Basic web UI	Polished web UI	Minimalist
Group sharing	Link + upload	File share	Library-first	Basic
Ease of deployment	Docker Compose	Docker/Manual	Docker Compose	Docker Compose

Immich excels in mobile-first design, real-time sync, and low-latency search. Nextcloud offers broader file management but a clunkier photo experience. PhotoPrism is a strong alternative for desktop-focused users but lacks native mobile backups. LibrePhotos is lightweight but less actively developed.

Security Considerations and Best Practices

Running a self-hosted service exposes access points. Implement the following for production use:

• Reverse Proxy: Use Nginx or Traefik with Let’s Encrypt SSL certificates.
• Authentication: Enable two-factor authentication (TOTP) for admin accounts.
• Network Segmentation: Place Immich in a Docker bridge network, exposing only required ports (2283).
• Backups: Regularly back up the PostgreSQL database (pg_dump) and the upload directory. Immich does not natively backup metadata; the database is the source of truth for albums, tags, and user settings.
• Updates: Subscribe to GitHub releases. Immich releases frequent updates (often weekly). Review changelogs for breaking changes, especially database schema migrations.

Troubleshooting Common Issues

• “No thumbnails generated”: Ensure the microservices container is running and has access to the same storage volumes. Check CPU usage; thumbnail generation can overwhelm low-power devices.
• Poor ML performance: Disable face detection for initial bulk imports. Run ML tasks during off-peak hours. Consider adding a GPU or using a pre-trained model cache.
• Mobile app won’t sync: Verify that the server URL in the app includes http:// or https:// and that the port is correct. Check firewall rules. Use a tool like netcat to test connectivity.
• Database connection refused: Confirm that the PostgreSQL container is healthy and that the .env file matches the database credentials. Restart the stack with docker-compose down && docker-compose up -d.

Scaling for Larger Libraries and Multiple Users

Immich is designed for scaling, but with caveats. The database can handle millions of assets, but full-text search and ML indexing become I/O-bound. For libraries exceeding 500,000 photos:

• Use SSD storage for the database volume.
• Allocate more CPU cores (8+) and RAM (16GB+).
• Consider separating the ML microservice onto a separate node using Docker Swarm or a VLAN.
• For multiple users (family or small teams), Immich supports user accounts with independent libraries and permissions. Administrators can set storage quotas and disable external sharing.

Customization and Theming

Advanced users can customize Immich through environment variables, such as modifying the default thumbnail sizes, changing image quality presets, or disabling specific ML modules. The web interface supports custom CSS injection for branding. The mobile apps do not currently support white-labeling.

Future Roadmap and Community Growth

Immich is under rapid development, with an active Discord community and over 30,000 GitHub stars. Planned features include:

• On-device ML: Running face detection and object recognition directly on mobile devices to reduce server load.
• Direct upload preview: A web uploader with real-time progress and drag-and-drop folder support.
• Tag-based automation: Automatic album creation based on ML tags or date patterns.
• Hardened storage: Support for encrypted archives using lightweight crypto backends.

Licensing and Support

Immich is released under the GNU Affero General Public License v3 (AGPLv3). This ensures that any modifications must remain open-source when used as a network service, protecting the community from proprietary forks. Commercial support is not officially available, but the active community provides troubleshooting via GitHub Issues and Discord.

Final Technical Notes

• File System Compatibility: Immich works with ext4, Btrfs, ZFS, and NFS. Avoid CIFS/SMB shares for the upload directory to prevent permission conflicts.
• Mobile App Privacy: The apps request camera and photo library access only for backup. No data is cached on the device beyond temporary thumbnails.
• Data Integrity: Immich does not calculate or store checksums (hash values) for assets. Users relying on archival-grade storage should implement external integrity monitoring.