LibrePhotos

LibrePhotos is a self-hosted, open-source photo management platform that brings cloud-photo-service capabilities entirely under your control. It automatically scans your file system, extracts EXIF and GPS metadata, and applies a multi-layer machine learning stack to organize, tag, and make your entire photo library searchable — all without sending a single image to an external server.

The backend is built on Django 5 with PostgreSQL and coordinates a set of specialized Flask microservices for face recognition, CLIP-based semantic embedding, and FAISS-powered similarity retrieval. Background jobs run through Django-Q2 and can handle libraries of hundreds of thousands of images asynchronously. A React 18 + TypeScript frontend and a React Native Android app give you polished web and mobile interfaces.

Machine learning is at the core rather than bolted on: faces are detected with InsightFace, clustered with HDBSCAN, and linked across your library so you can search by person. Images are embedded with SigLIP 2 (ONNX) and sentence-transformers so natural-language queries like “sunset at the beach” return semantically relevant results. Optional on-device LLM captioning via llama.cpp (Moondream or Mistral in quantized GGUF format) generates human-readable descriptions without any cloud API calls.

Deployment is Docker Compose-based with prebuilt images available, and a Kubernetes manifest is included for larger setups. System requirements start at 4 GB RAM and 2 CPU cores, with 8 GB+ recommended when ML features are active.

What You Get

• AI Face Recognition and Clustering - Detects faces using InsightFace and groups them with HDBSCAN clustering so you can name people and search across your entire library by individual.
• Semantic Image Search - Embeds every photo with SigLIP 2 (ONNX) via sentence-transformers and stores embeddings in a per-user FAISS index, letting you search with natural language like “mountain sunrise” or “dog in snow” with no cloud API.
• Automatic Event Albums - Groups photos by temporal and spatial proximity (within 36-hour windows) and auto-generates titles like “Thursday in Berlin” using reverse geocoding and LLM captioning.
• On-Device LLM Captioning - Runs Moondream or Mistral in quantized GGUF format via llama-cpp-python to generate natural-language image descriptions entirely on your hardware.
• BK-Tree Duplicate Detection - Finds exact byte-for-byte copies by MD5 and near-duplicate images by perceptual hash using a Burkhard-Keller tree, optimized to handle 300k+ photos with under 200 MB RAM.
• Multiuser Library Management - Supports separate libraries per user with private albums, fine-grained sharing permissions, and role-based access control so multiple family members or team members can coexist.
• RAW, Video, and Metadata Support - Handles RAW formats (CR2, NEF, etc.) via ImageMagick/Wand, video files via FFmpeg, and extracts comprehensive EXIF/GPS metadata with PyExifTool for timeline and map views.
• React and React Native Clients - Ships a full-featured web client built on Mantine, TanStack Router, and MapLibre GL, plus an Android mobile app in React Native for on-the-go access.

Common Use Cases

• Replacing Google Photos or iCloud for a privacy-conscious household - A family installs LibrePhotos on a home server, imports 50,000 photos, and uses face recognition to tag grandparents and children — keeping all images off cloud infrastructure while retaining album and search features.
• Managing a large personal archive as a photographer - A hobbyist photographer with 150,000+ RAW files uses semantic search to locate “foggy forest morning” shots across a decade of shoots, and duplicate detection to clean up burst-mode redundancies before an external backup run.
• Running a shared team media library - A small documentary crew sets up LibrePhotos on a local server, uses multiuser libraries so each member has a private space, and shared albums for production stills — with map view to correlate field locations with shoot dates.
• Self-hosting as an alternative to Immich or Photoprism - A developer who wants the deepest ML feature set (on-device LLM captioning, CLIP semantic search, InsightFace recognition) picks LibrePhotos and deploys it via Docker Compose with the recommended 8 GB RAM configuration.
• Archiving event photos for a club or organization - An event organizer ingests photos from 30 different contributors, uses person search to find all shots of key speakers, and generates shareable public albums — all on a private server with no external hosting costs.

Under The Hood

Architecture LibrePhotos adopts a microservices-within-a-monorepo approach: a central Django REST Framework API acts as the orchestration hub, delegating inference work to a set of independently running Flask services — one for face detection and embedding, one for CLIP semantic embedding generation, and one for FAISS-based nearest-neighbor similarity search. Each service communicates with the Django backend via HTTP and can spin down when idle to reduce memory pressure. Background photo processing, face clustering, and album generation are handled by Django-Q2 workers with gevent-based async I/O, while Nginx routes web, API, and media traffic as a reverse proxy. The separation between API, ML inference, media processing, and background jobs is well-enforced, making individual components independently scalable at the cost of operational complexity in a multi-container deployment.

Tech Stack The backend runs Python 3.11 on Django 5 with Django REST Framework, drf-spectacular for OpenAPI docs, and djangorestframework-simplejwt for JWT authentication. PostgreSQL stores all metadata, face encodings, and CLIP embeddings, with django-cryptography for field-level encryption of sensitive fields. Machine learning spans InsightFace and the face_recognition library for detection and embeddings, HDBSCAN for density-based face clustering, sentence-transformers and SigLIP 2 (ONNX via onnxruntime) for semantic image search, FAISS for in-memory vector retrieval, BLIP and im2txt for image captioning, places365 for scene classification, and llama-cpp-python (Moondream/Mistral GGUF) for on-device LLM captioning. Media handling uses Pillow, pyvips, Wand, FFmpeg, and PyExifTool. The React 18 TypeScript frontend is built with Vite and uses Mantine components, TanStack Router and Query, MapLibre GL for geo views, and i18next for internationalization, with a separate React Native Android client.

Code Quality Test coverage is meaningful across the backend with tests for API robustness and security edge cases, duplicate detection algorithms, face extraction pipelines, EXIF parsing, photo metadata handling, thumbnail migration, and user management — all organized by feature domain and using Django’s TestCase with DRF’s APIClient. The duplicate detection module documents its memory optimization rationale inline, comparing old (10 GB RAM) versus new (100-200 MB) behavior at scale. Ruff enforces formatting with pyupgrade, isort, and Django-aware lint rules; a renovate.json with automated minor/patch merging keeps dependencies current. Type annotations are present in service-layer code but inconsistent across older modules, and error handling is generally explicit with logged exceptions and HTTP status codes rather than silent failures.

What Makes It Unique LibrePhotos stands out by combining a multi-layer self-hosted ML inference stack into a single deployable system: per-user FAISS vector indices for visual similarity without a cloud embedding API, CLIP/SigLIP2 semantic search that responds to natural language queries entirely on-premises, and on-device LLM captioning via llama.cpp with quantized multimodal models. The BK-Tree duplicate detection implementation is explicitly memory-optimized for libraries exceeding 300,000 photos, processing in configurable batches to cap RAM at around 200 MB regardless of library size. The recent consolidation of five separate repositories into a path-filtered monorepo — with preserved commit history per file — reflects a maturing project governance model that makes cross-app changes (backend API + frontend + mobile) easier to coordinate.

Self-Hosting

LibrePhotos is released under the MIT License, one of the most permissive open-source licenses available. You can use it commercially, modify it freely, incorporate it into proprietary systems, and redistribute it without any copyleft obligations — the only requirement is preserving the copyright notice. There are no license keys, no feature gating by tier, and no “open core” commercial extensions. Every capability in the repository, including the full ML pipeline, is available to anyone who deploys it.

Running LibrePhotos yourself means operating a stack of five or more Docker containers: a PostgreSQL database, the Django backend, a Nginx reverse proxy, the React frontend, and at least two ML inference microservices (face recognition and CLIP embeddings) that can scale with additional workers. The recommended production configuration requires 8 GB RAM for smooth ML feature operation, with 4 GB as a functional minimum that will feel constrained on large libraries. You are responsible for your own data backups, PostgreSQL maintenance, container updates, and disk provisioning for your photo library. The project does not publish release tags on GitHub — deployments track Docker image tags (latest, dev) — so staying on a stable version requires pinning image tags manually.

There is no official hosted or managed version of LibrePhotos, so there is no SaaS tier offering managed upgrades, 24/7 support SLAs, or cloud backup. Community support happens via a Discord server and GitHub issues. If you need high-availability deployment, you will need to set up PostgreSQL replication, container orchestration (a Kubernetes manifest is included), and your own monitoring. The trade-off is complete data sovereignty and no per-user or per-storage pricing — for privacy-conscious users or organizations that already operate their own infrastructure, this is often exactly what they want.