LibrePhotos
A self-hosted, open-source photo management service with automatic face recognition, object detection, and semantic search — powered by modern machine learning.
Repository layout
This is a monorepo that consolidates what was previously five separate repositories.
| Path | What it is | Previous repo |
|---|
apps/backend/ | Django 6 API, machine-learning pipelines, background jobs | librephotos |
apps/frontend/ | React 19 + Vite web client, i18next localization | librephotos-frontend |
apps/mobile/ | Expo mobile app (Android and iOS), offline-first | librephotos-mobile |
apps/docs/ | Docusaurus site published to https://docs.librephotos.com | librephotos.docs |
deploy/ | Dockerfiles, Compose configs, proxy, Kubernetes manifests | librephotos-docker |
Commit history from all five repositories is preserved — git log --follow apps/<app>/<file> works across the move.
Installation
Pick the deployment that fits your setup. Step-by-step guides are in the documentation.
System Requirements
| Resource | Minimum | Recommended |
|---|
| RAM | 4 GB | 8 GB+ |
| Storage | 10 GB (plus your photo library) | SSD recommended |
| CPU | 2 cores | 4+ cores |
| OS | Any Docker-compatible OS, or Windows | Linux |
Note: Machine learning features (face recognition, scene classification, image captioning) are memory-intensive. 8 GB+ RAM is strongly recommended for smooth operation.
Features
- Photos in all common formats, including RAW, HEIC and JPEG XL
- Videos and live photos
- Timeline grouped by day and place, plus favorites, recent additions and memories
- Scans your existing folders and accepts uploads from the web and mobile apps
- Multiple users, shared albums and public links
- Albums generated from events, like "Saturday in Lisbon"
- Face detection and clustering: name a person once and the rest is suggested
- Places and a map from reverse geocoding
- Tags and generated captions for every photo
- Semantic search ("dog on a beach") and search by metadata
- RAW+JPEG pairs kept as one photo, burst and bracket stacks, and duplicate detection
- Single sign-on through OpenID Connect
- Expo mobile app for Android and iOS
Tech Stack
Backend
Frontend
Machine Learning
- Face detection: InsightFace
- Face classification/clustering: hdbscan clustering and a scikit-learn multilayer perceptron, both ported to numpy
- Image captioning: LFM2.5-VL, prompted with the recognised people and the place
- Tagging, semantic search and similar photos: OpenCLIP ViT-B/32 (DataComp-XL, MIT licence)
- Semantic search: CLIP ViT-B/32 with an exact inner-product index in numpy
- ML runtime: ONNX Runtime for every model, no PyTorch
- Reverse geocoding: geopy
Infrastructure
API Documentation
After starting LibrePhotos, interactive API docs are available at:
- Swagger UI:
http://localhost:3000/api/swagger
- ReDoc:
http://localhost:3000/api/redoc
Development
See CONTRIBUTING.md and the per-app READMEs:
The Docker Compose-based dev environment lives in deploy/compose/ and is described in the development install guide.
How to help out
- ⭐ Star this repository if you like this project!
- 🚀 Developing: Get started in less than 30 minutes by following this guide. Also see our CONTRIBUTING.md for detailed development setup, code quality standards, and PR guidelines.
- 🗒️ Documentation: Improving the documentation is as simple as submitting a pull request here
- 🧪 Testing: If you want to help find bugs, use the
dev tag and update it regularly. If you find a bug, open an issue.
- 🧑🤝🧑 Outreach: Talk about this project with other people and help them to get started too!
- 🌐 Translations: Make LibrePhotos accessible to more people with weblate.
- 💸 Donate to the developers of LibrePhotos
License
This project is licensed under the MIT License.
