selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

librephotos logo

Self-host librephotos

1.5.1

Photo library with face recognition and semantic search

ReleaseOpen SourceMIT
Updatedlast week
LanguagePython
Setup difficultyModerate
MobileNative app
ThemeDark mode
Stars
8 140
CPU
2 cores
RAM
4 GB
Storage
10 GB (plus your photo library)
Port
8001 (Backend API port; the single-container image serves the web app here too (run with -p 3000:8001))
Docker
reallibrephotos/librephotos-unified
Install with Docker
Timeline in the dark theme: photos grouped by day with the places they were takenTimeline view of the library in the light theme

What is librephotos?

librephotos alternatives

All self-hosted alternatives to Google Photos → All self-hosted alternatives to Synology Photos →

Should you self-host librephotos?

librephotos scores 71/100 on selfhost.directory (how scoring works) and ranks #2 of 41 in Photo Management. It has 8 140 GitHub stars, +51 in the last 30 days.

It shipped 14 stable releases in the past year. The latest, 1.5.1, came out on 31 October 2026. New versions land roughly every 5 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is Immich (93/100, 118 598 stars). It scores higher overall, so compare the two before you pick. See librephotos vs Immich side by side.

Features

  • Auto-generated event albums
  • Automatic image captions
  • Duplicate detection and stacks
  • Face detection and clustering
  • Folder scanning and upload
  • GPU acceleration for MLGPU support for the single-container image is announced for a release after 1.4.0.
  • Multi-user with shared albums
  • OCR text recognition
  • OpenID Connect single sign-on
  • Places and map view
  • RAW and HEIC support
  • REST API with interactive docs
  • Semantic Search
  • Video and live photo support

librephotos README

Discord Read the docs GitHub contributors License: MIT

LibrePhotos

The LibrePhotos timeline, with photos grouped by day and place 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.

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
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.

How to install librephotos

Install librephotos with Docker

Environment variables
SERVE_FRONTEND, DB_BACKEND, SECRET_KEY, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS, ALLOW_UPLOAD, CSRF_TRUSTED_ORIGINS, NUM_PROXIES
mkdir -p /home/yourusername/librephotos/{db,protected_media,logs}
sudo docker run -d \
  --name librephotos \
  --restart unless-stopped \
  -p 3000:8001 \
  -v /home/yourusername/librephotos/db:/db \
  -v /home/yourusername/librephotos/protected_media:/protected_media \
  -v /home/yourusername/librephotos/logs:/logs \
  -v /path/to/your/photos:/data \
  -e SERVE_FRONTEND=true \
  -e DB_BACKEND=sqlite \
  reallibrephotos/librephotos-unified:latest

Access: http://localhost:3000

Single container with internal SQLite; an external PostgreSQL variant is documented too.

How to configure librephotos

  • MAPBOX_API_KEY(empty)The key for the geocoding provider, as in the example above.
  • ALLOW_UPLOADtrueWhether uploads are allowed. An empty value leaves them allowed.
  • VITE_APP_WDYRfalseWhy Did You Render — logs to the browser console the reason each React component re-rendered. Only has an effect on the dev compose stack (docker-compose.dev.yml), and only for the literal string "true".
  • ONNX_PROVIDERSCUDA if available, then WebGPU if it found a GPU, then CPUComma-separated ONNX Runtime execution providers, most preferred first; the first one decides the device. CPUExecutionProvider keeps the models off the GPU, for example to leave it to another application, and skips the GPU check. Names the installed ONNX Runtime does not offer are skipped.
  • ONNX_INTRA_OP_THREADSONNX Runtime's default (one per physical core)How many threads one model may use at a time. See Threads per model.

librephotos releases & version history

@ Every self-hosted release, weekly

One Monday email with the week's stable releases across the directory.

FAQ

Why are videos not playing and showing a 404 error?

Usually the codec cannot be decoded in that browser (often H.265 in Firefox), which LibrePhotos transcodes automatically on current releases, or the file permissions are wrong — setting directories to 755 and files to 644 fixes the permission case.

Can two users share one photo folder?

No — each photo belongs to exactly one user and overlapping scan directories are refused. Households should keep one library and share albums, or share a whole library read-only.

Why is the scan directory not mounted read-only?

It can be mounted read-only, but then writing metadata back into files, uploading and deleting photos stop working; only the metadata write-back reports failures nicely.

Why do I get "error decoding 'Volumes[0]': invalid spec: :/data" or "The scanDirectory variable is not set"?

That almost always means the bundled librephotos.env template was never renamed to .env, so Docker Compose cannot read your variables.

Why does a scan on Proxmox always fail after importing a few images?

A QEMU/Proxmox guest using the default kvm64 CPU type lacks instruction flags such as SSE and AVX, so the scan crashes with an Illegal instruction error. Switch the VM's CPU type to Host (or add the missing flags in the qm.conf file).

More in Photo Management

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…