[][discord] [](https://librephotos.com/)
[](https://docs.librephotos.com/) [](https://github.com/LibrePhotos/librephotos/graphs/contributors) [](LICENSE)
# LibrePhotos
Mockup designed by rawpixel.com / Freepik
A self-hosted, open-source photo management service with automatic face recognition, object detection, and semantic search โ powered by modern machine learning.
- **Stable** demo is available here: https://demo1.librephotos.com/ . User is ```demo```, password is ```demo1234``` (with sample images).
- Latest **development** demo is available here: https://demo2.librephotos.com/ (same user/password)
- You can watch development videos on [Niaz Faridani-Rad's channel](https://www.youtube.com/channel/UCZJ2pk2BPKxwbuCV9LWDR0w)
- You can join our [Discord][discord].
## Repository layout
This is a monorepo that consolidates what was previously five separate repositories.
| Path | What it is | Previous repo |
|---|---|---|
| [`apps/backend/`](apps/backend/) | Django 5 API, machine-learning pipelines, background jobs | `librephotos` |
| [`apps/frontend/`](apps/frontend/) | React 18 + Vite web client, i18next localization | `librephotos-frontend` |
| [`apps/mobile/`](apps/mobile/) | React Native mobile client (Android) | `librephotos-mobile` |
| [`apps/docs/`](apps/docs/) | Docusaurus site published to https://docs.librephotos.com | `librephotos.docs` |
| [`deploy/`](deploy/) | Dockerfiles, Compose configs, proxy, Kubernetes manifests | `librephotos-docker` |
Commit history from all five repositories is preserved โ `git log --follow apps//` works across the move.
## Installation
Step-by-step installation instructions are available in our [documentation](https://docs.librephotos.com/docs/installation/standard-install).
### 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 | Linux |
> **Note:** Machine learning features (face recognition, scene classification, image captioning) are memory-intensive. 8 GB+ RAM is strongly recommended for smooth operation.
## Features
- Support for all types of photos including raw photos
- Support for videos
- Timeline view
- Scans pictures on the file system
- Multiuser support
- Generate albums based on events like "Thursday in Berlin"
- Face recognition / Face classification
- Reverse geocoding
- Object / Scene detection
- Semantic image search
- Search by metadata
## Tech Stack
### Backend
- **Framework:** [Django 5](https://www.djangoproject.com/) with [Django REST Framework](https://www.django-rest-framework.org/)
- **Database:** [PostgreSQL](https://www.postgresql.org/)
- **Task Queue:** [Django-Q2](https://github.com/django-q2/django-q2)
- **Image Conversion:** [ImageMagick](https://github.com/ImageMagick/ImageMagick)
- **Video Conversion:** [FFmpeg](https://github.com/FFmpeg/FFmpeg)
- **Exif Support:** [ExifTool](https://github.com/exiftool/exiftool)
### Frontend
- **UI:** [React 18](https://react.dev/) with [TypeScript](https://www.typescriptlang.org/)
- **Build Tool:** [Vite](https://vite.dev/)
- **Component Library:** [Mantine](https://mantine.dev/)
- **Routing:** [TanStack Router](https://tanstack.com/router)
- **Data Fetching:** [TanStack Query](https://tanstack.com/query)
- **Maps:** [MapLibre GL](https://maplibre.org/)
- **Internationalization:** [i18next](https://www.i18next.com/)
### Machine Learning
- **Face detection:** [face_recognition](https://github.com/ageitgey/face_recognition)
- **Face classification/clustering:** [scikit-learn](https://scikit-learn.org/) and [hdbscan](https://github.com/scikit-learn-contrib/hdbscan)
- **Image captioning:** [im2txt](https://github.com/HughKu/Im2txt)
- **Scene classification:** [places365](http://places.csail.mit.edu/)
- **Reverse geocoding:** [geopy](https://github.com/geopy/geopy)
### Infrastructure
- **Deployment:** [Docker](https://www.docker.com/) & [Docker Compose](https://docs.docker.com/compose/)
- **Reverse Proxy:** [Nginx](https://nginx.org/)
### 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](CONTRIBUTING.md) and the per-app READMEs:
- [Backend](apps/backend/README.md)
- [Frontend](apps/frontend/README.md)
- [Mobile](apps/mobile/README.md)
- [Docs site](apps/docs/README.md)
The Docker Compose-based dev environment lives in [`deploy/compose/`](deploy/compose/) and is described in the [development install guide](https://docs.librephotos.com/docs/development/dev-install).
## How to help out
- โญ **Star** this repository if you like this project!
- ๐ **Developing**: Get started in less than 30 minutes by following [this guide](https://docs.librephotos.com/docs/development/dev-install). Also see our [CONTRIBUTING.md](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](https://github.com/LibrePhotos/librephotos/tree/dev/apps/docs)
- ๐งช **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](https://hosted.weblate.org/engage/librephotos/).
- ๐ธ [**Donate**](https://github.com/sponsors/derneuere) to the developers of LibrePhotos
## License
This project is licensed under the [MIT License](LICENSE).
[discord]: https://discord.gg/xwRvtSDGWb