LibrePhotos: A Self-Hosted Photo Manager with ML-Powered Face Recognition and Semantic Search
A self-hosted open source photo management service.
At a glance
- What is it?
- LibrePhotos is an MIT-licensed, self-hosted photo management service that uses machine learning to organize photo libraries by face, object, event, and semantic query. It consolidates five previous repositories into a single monorepo and deploys via Docker Compose, requiring at least 4 GB of RAM to run its ONNX-based ML pipeline.
- Who is it for?
- LibrePhotos suits home server users and small teams who want Google Photos-style features without depending on a cloud service. The 8 GB RAM recommendation is not conservative: the machine learning pipeline runs inference on the local host, and machines near the 4 GB minimum will see slow batch processing.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What LibrePhotos Is and Why It Exists
Cloud photo services index your library on remote infrastructure and return search results from that. LibrePhotos replicates the core capabilities of that model on hardware you control: face detection and clustering, object and scene tagging, semantic image search, reverse geocoding, and timeline view all run locally.
The README describes LibrePhotos as a self-hosted, open-source photo management service with automatic face recognition, object detection, and semantic search, powered by modern machine learning. The intended users are people who want to search their photos by content, find all images of a particular person, or generate event-based albums without uploading their library to a third-party service.
The project supports multi-user deployments, meaning a household or small team can share a single installation with separate libraries and accounts. It handles RAW photo files (via LibRaw), video files (via FFmpeg), and reads EXIF metadata through ExifTool.
Monorepo Architecture: Five Apps in One Repository
The repository consolidates five previously separate projects: a Django backend, a React frontend, an Expo mobile app, a documentation site, and a deploy configuration directory. The README provides a directory table:
The `apps/backend/` directory contains a Django 5 API with Django REST Framework, a PostgreSQL database, Django-Q2 for background job queuing, and all ML pipelines. The `apps/frontend/` directory holds a React 18 and Vite web client with Mantine components, TanStack Router for navigation, TanStack Query for data fetching, and MapLibre GL for map display. The `apps/mobile/` directory contains an Expo application targeting Android and iOS with offline-first behavior. The `apps/docs/` directory is a Docusaurus site published to docs.librephotos.com. The `deploy/` directory contains Dockerfiles, Docker Compose configurations, Nginx proxy configuration, and Kubernetes manifests.
The README notes that commit history from all five original repositories is preserved. Running `git log --follow apps/<app>/<file>` traces file history across the consolidation boundary.
The ML Pipeline: ONNX Runtime With No PyTorch Dependency
The machine learning component is the most distinctive part of LibrePhotos's architecture. All models run through ONNX Runtime, which the README explicitly calls out as an alternative to PyTorch. This choice avoids the several-gigabyte PyTorch installation and reduces the compute requirements compared to a PyTorch-based setup.
The README documents each model role separately. Face detection uses InsightFace. Face clustering and classification use scikit-learn and hdbscan, which group detected faces into identity clusters without requiring labeled training data. Image captioning uses LFM2.5-VL-450M-ONNX, prompted with the recognized people and the detected location. Object and scene tagging uses either MobileCLIP-S2 or SigLIP 2. Semantic image search uses CLIP ViT-B/32 with FAISS for vector indexing, which allows queries like 'dog at the beach' to retrieve matching photos by visual meaning rather than file metadata.
Reverse geocoding uses the geopy library to translate GPS coordinates embedded in photo EXIF data into readable place names.
Deploying LibrePhotos and Verifying the Installation
LibrePhotos deploys via Docker and Docker Compose. The README states that step-by-step installation instructions are in the documentation at docs.librephotos.com, and does not include shell commands in the README itself.
After a successful deployment, the web interface is served on port 3000. Interactive API documentation is available at two endpoints:
http://localhost:3000/api/swagger
http://localhost:3000/api/redocThe Swagger UI at `/api/swagger` provides a browsable interface to all backend endpoints and can be used to verify that the API layer is running correctly. The ReDoc view at `/api/redoc` presents the same API in a documentation format. Both are generated from the Django REST Framework's schema and reflect the current running instance.
Hardware Requirements and the Memory Constraint
The README includes a system requirements table with explicit minimums and recommendations. The minimum configuration is 4 GB RAM, 10 GB storage (excluding the photo library), a 2-core CPU, and any Docker-compatible operating system. The recommended configuration is 8 GB or more of RAM and an SSD.
The README's note is direct: 'Machine learning features (face recognition, scene classification, image captioning) are memory-intensive. 8 GB+ RAM is strongly recommended for smooth operation.' This is a meaningful constraint for home servers. A machine at the 4 GB minimum will process ML jobs but will do so slowly, and may swap under concurrent workloads. The ONNX Runtime reduces memory versus a PyTorch stack, but the face clustering and FAISS indexing steps still require loading model weights and index structures into RAM.
Storage requirements depend almost entirely on library size. The 10 GB figure covers the operating system, database, and application; the photo library adds its full size on top of that.
LibrePhotos vs Immich
Immich is a well-known self-hosted photo alternative focused on fast mobile-device synchronization and a Google Photos-like web interface. The fundamental difference is emphasis. Immich prioritizes the synchronization pipeline: fast upload from phone, timeline browsing, and album sharing. LibrePhotos prioritizes ML-powered search and organization: event-based album generation, semantic image queries, and face identity clustering.
Immich is built on Node.js and TypeScript for its backend. LibrePhotos uses Python and Django. Both deploy via Docker Compose. The choice between them depends on whether the primary use case is keeping mobile photos backed up and browsable, or building a searchable archive of an existing large photo library.
LibrePhotos's choice of ONNX Runtime over PyTorch as the ML execution environment is a meaningful technical distinction. PyTorch installations typically require several gigabytes of disk space and separate CUDA configuration for GPU acceleration. ONNX Runtime keeps the installation smaller and provides a consistent CPU inference path that works without GPU drivers. For home server hardware without a discrete GPU, this choice reduces operational complexity. The FAISS vector index used for semantic search is a well-established library from Meta AI Research for high-efficiency similarity search, and its integration here enables the 'search by meaning' queries that distinguish LibrePhotos from simpler gallery tools.
Maintenance Status, Mobile App, and Licensing
The last push to the dev branch was on 2026-09-17, and the most recent release, 1.1.0, was published on 2026-08-28. The project publishes releases through GitHub. An earlier release, 1.0.3, specifically addressed a fix for the user list popup for non-admin users, which shows the project handles smaller usability issues in point releases.
The mobile application in `apps/mobile/` targets Expo SDK 57 and supports both Android and iOS. The README describes it as offline-first, suggesting local caching of photo thumbnails or metadata for use when the server is not reachable. The root package.json pins the Expo SDK version with explicit commentary about why: expo-router's peer dependency on the CLI and React version must stay in lockstep with the app's own SDK version to avoid nested dependency conflicts. The comment in the package.json names jest-expo@57 as the specific constraint.
LibrePhotos is MIT licensed. The monorepo package.json at the root serves as an npm workspace for the mobile app only; the frontend and docs apps maintain separate package managers (the frontend uses Yarn). Translations are managed through Weblate at hosted.weblate.org.
The `CLAUDE.md` file at the repository root indicates the project has documented instructions for AI coding assistants. The `CONTRIBUTING.md` file covers the development setup process and code quality standards. The `plans/` directory suggests the project documents feature planning alongside the source code. For development work, the Docker Compose environment in `deploy/compose/` is used, and the README directs new contributors to the development install guide at docs.librephotos.com.
Editorial conclusion
LibrePhotos suits home server users and small teams who want Google Photos-style features without depending on a cloud service. The 8 GB RAM recommendation is not conservative: the machine learning pipeline runs inference on the local host, and machines near the 4 GB minimum will see slow batch processing. Before deploying, verify your host has Docker support and review the system requirements table in the README. The documentation at docs.librephotos.com covers the standard installation procedure; the repository itself does not include shell-level setup instructions.
Frequently asked questions
Is LibrePhotos a free alternative to Google Photos?
LibrePhotos is an MIT-licensed, self-hosted alternative that provides features similar to Google Photos, including face recognition, object detection, timeline view, and semantic search. It runs on your own hardware using Docker; there is no hosted version or cloud service.
How does LibrePhotos compare to Piwigo?
The README does not document a comparison with Piwigo. LibrePhotos focuses on ML-powered organization including automatic face recognition, semantic search via CLIP embeddings, and event detection. Piwigo is a PHP-based gallery system that focuses on photo sharing and album management rather than local ML inference.
How does LibrePhotos compare to PhotoPrism and Immich?
All three are self-hosted photo managers deployed via Docker. LibrePhotos uses ONNX Runtime for ML inference with no PyTorch dependency and includes CLIP-based semantic search and face clustering. The README does not document a comparison with PhotoPrism or Immich directly.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/librephotos-librephotos)