LibrePhotos

_{Sample photos from Pexels, see the credits.}

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.

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.

• Single container: one image serves the API and the web app, recommended for most people
• Docker Compose: separate backend, frontend and proxy containers, with optional NVIDIA GPU acceleration
• Kubernetes: Kustomize manifests in deploy/k8s
• Unraid
• Windows standalone: one folder with librephotos.exe, no Docker or Python

System Requirements

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

• Framework: Django 5 with Django REST Framework
• Database: PostgreSQL
• Task Queue: Django-Q2
• RAW Conversion: LibRaw via rawpy
• Video Conversion: FFmpeg
• Exif Support: ExifTool

Frontend

• UI: React 19 with TypeScript
• Build Tool: Vite
• Component Library: Mantine
• Routing: TanStack Router
• Data Fetching: TanStack Query
• Maps: MapLibre GL
• Internationalization: i18next

Machine Learning

• Face detection: InsightFace
• Face classification/clustering: scikit-learn and hdbscan
• 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 FAISS
• ML runtime: ONNX Runtime for every model, no PyTorch
• Reverse geocoding: geopy

Infrastructure

• Deployment: Docker & Docker Compose
• Reverse Proxy: Nginx

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: - Backend - Frontend - Mobile - Docs site

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.