How to Use PhotoPrism: The Beginner's Guide (First Docker Run, First Library Scan, AI Search, and the MariaDB Lesson)

CodexFuse Team · 2026-10-31T17:45:31.987Z · 14 min read

Learn how to use PhotoPrism: first Docker run, first library scan, AI search and face recognition, the originals-folder rule, and the SQLite-vs-MariaDB lesson.

What is PhotoPrism, exactly?

PhotoPrism is a self-hosted, AI-powered photos app that organizes a photo library you already have. You run it on your own server — usually with Docker — point it at your folders of pictures, and it builds a searchable gallery with face recognition, automatic labels, and a map view, without sending a single photo to someone else's cloud. That is the short answer to how to use PhotoPrism: install it, give it your photos, let it index them, and search them like you would Google Photos.

It is open-source software under the AGPL-3.0 license, in development since 2018, and as of October 31, 2026 it carries roughly 40,381 stars on GitHub — one of the most-starred self-hosted apps of any kind. The latest release landed on October 29, 2026 (tag 261029-963b58c50) with an upgraded database layer, experimental PostgreSQL support, OAuth and MCP tools, and a move of image classification to new ONNX models with NVIDIA GPU support. PhotoPrism describes itself on its official Docker page as an "AI-Powered Photos App for the Decentralized Web" that recognizes the faces of your family and friends.

If you are brand new to containers, the fastest way to follow this photoprism tutorial is to run everything in Docker — our Docker beginner guide covers the Docker setup you will need. You will also want a machine to run it on; our what is VPS hosting guide explains the kind of server this fits best.

How do you use PhotoPrism for the first time?

You check the hardware minimums, download the official compose file, set a strong admin password, start the stack, sign in, choose how your photos get in, run the first index scan, and then harden the install. Here is the complete arc this photoprism for beginners guide follows:

1. Confirm the machine has at least 2 CPU cores, 3 GB of RAM, and 4 GB of swap.
2. Download the official compose.yaml and change PHOTOPRISM_ADMIN_PASSWORD from the default.
3. Start the stack with docker compose up -d.
4. Open http://localhost:2342/ and sign in as admin.
5. Decide between indexing your photos in place (the originals folder) or staging them through the import folder.
6. Run Library > Index > Complete Rescan for the first library scan.
7. Search your library — try faces, labels, and places — then secure the install with HTTPS and two-factor authentication.

The rest of this guide walks through each step in detail, including the two decisions beginners get wrong most often: the originals folder and the database choice.

What does PhotoPrism need to run?

PhotoPrism needs at least 2 CPU cores, 3 GB of physical memory, a 64-bit operating system, and 4 GB of swap. The official docs add two rules that are easy to miss: RAM should roughly match the CPU core count, and you must never set a hard memory limit on the container — doing so causes unexpected restarts.

Storage speed matters more than most beginners expect. PhotoPrism constantly reads image files while indexing, so the docs strongly recommend an SSD for the database, cache, and storage folders; an NVMe drive noticeably shortens first-scan times on large libraries. The CPU and GPU handle the AI inference for object detection and face recognition — the built-in models run fine on CPU for small libraries, but a GPU is advisable if you want the AI features to feel fast. The October 2026 release added NVIDIA GPU support alongside the new ONNX classification models.

These are my own syntheses of the official minimums plus the homelab guidance from independent install walkthroughs — treat them as starting points, not guarantees. A Raspberry Pi can technically run PhotoPrism (there is a full community tutorial for it), but indexing will be slow; a small VPS or home server is the comfortable minimum.

How do you install PhotoPrism with Docker?

You download the official compose.yaml, change the admin password in it, and start the stack with docker compose up -d. Docker is the officially supported path and the one every independent guide uses, so this photoprism install docker section sticks to it.

mkdir ~/photoprism
cd ~/photoprism
wget https://dl.photoprism.app/docker/compose.yaml
docker compose up -d

Before you run that last command, open compose.yaml and change these values:

PHOTOPRISM_ADMIN_USER: "admin"
PHOTOPRISM_ADMIN_PASSWORD: "insecure"   # change this BEFORE the first start
PHOTOPRISM_AUTH_MODE: "password"         # or "public" (disables login entirely)
PHOTOPRISM_SITE_URL: "http://localhost:2342/"

The compose file starts two services: photoprism/photoprism:latest (use the preview tag if you want pre-release builds) and a MariaDB database. The web UI listens on port 2342, mapped as 2342:2342 — if that port is taken, change only the left-hand side. Your photo files live at ~/Pictures on the host, mounted into the container as /photoprism/originals. Once this self hosted photo gallery docker stack is up, every later section of this guide happens in the browser.

Here is the admin-password lesson every beginner must learn: the admin account is created automatically from the compose values at first start, the password must be at least 8 characters, and there is no default if you provide none. Critically, the environment variable stops working after the first start — to change the password later you must use the CLI: docker compose exec photoprism photoprism passwd [username]. Set a strong password now, because recovering later is more work.

What is the originals folder, and how should you use it?

The photoprism originals folder (/photoprism/originals inside the container) is where your photo files live, and PhotoPrism indexes them in place — leaving file names and folder structure exactly as they were. Most users with an existing library want exactly this: index the originals directly instead of using the optional import feature.

PhotoPrism deliberately leaves your files alone. The official FAQ lists only six situations where files in the originals folder get modified: rotating an image, renaming during unstacking, importing or uploading, deleting, storing sidecars in a configured folder, and writing over WebDAV. Everything else — thumbnails, metadata, face data — goes into the separate storage folder. Hidden files (names starting with ., @, _., or __) are ignored during indexing, and you can add a .ppignore file to skip folders you do not want scanned.

If your collection spans several drives or shares — the classic photoprism external library situation — mount each one as a subfolder of /photoprism/originals (for example /photoprism/originals/nas-photos). PhotoPrism treats them as one library. The alternative is the import folder (/photoprism/import), an optional staging area: drop files there, open Library > Import, and PhotoPrism moves or copies them into the library organized by year and month with canonical file names.

How do you run your first library scan?

You open Library > Index, select Complete Rescan, and press Start — then watch the indexer work on the Logs tab while the counts in the navigation update. Your photos become visible in search results and albums successively as indexing progresses; you do not wait for the whole library to finish before browsing.

This photoprism setup arc is the same on a VPS, a home server, or a NAS — only the storage mounts change. A few indexing facts worth knowing before your photoprism first run. For RAW and HEIF originals, PhotoPrism creates JPEG sidecar files during indexing — this is required for image classification, face recognition, and displaying them in a browser at all. Files uploaded over WebDAV (for example from a phone sync app) trigger an automatic rescan roughly five minutes later, controlled by PHOTOPRISM_AUTO_INDEX (default 300 seconds). You can also schedule regular rescans with PHOTOPRISM_INDEX_SCHEDULE so new files are picked up on their own.

If some pictures are still missing after a completed scan, check Library > Review first — photos land there when they are low quality or have incomplete metadata, and you can turn the Review feature off in Settings if you would rather see everything. After any change outside the app — adding, removing, or editing files — go back to Library and click Start to update the index.

How does PhotoPrism's AI search and face recognition work?

During indexing, PhotoPrism runs a multi-stage pipeline — detect, then turn detections into embeddings, then cluster similar faces with DBSCAN — so photoprism face recognition and photoprism ai search work with no extra setup. The built-in models classify your pictures and recognize faces automatically; labels are available the moment indexing finishes.

For new libraries, detection uses the YuNet model and face embeddings come from SFace, both running on the ONNX runtime. Libraries created with older versions keep using FaceNet on TensorFlow, so behavior can differ slightly between an old and a fresh install. The October 2026 release moved content classification and NSFW detection to new ONNX models, added NVIDIA GPU support, and — importantly — dropped support for custom TensorFlow models defined in vision.yml; if an old guide tells you to hand-tune a TensorFlow model, replace that step with the new ONNX workflow. Face recognition is included in the free Community edition, not gated behind a paid tier.

Search is where the AI pays off. The search bar accepts plain words ("cats", "beach") plus filters such as label:cat, and the expanded toolbar adds country, year, month, camera, color, and category filters. If you want richer, more descriptive captions than the built-in models produce, you can connect a self-hosted Ollama instance, Ollama Cloud, or the OpenAI API at any time — including for pictures that were already indexed. The official first-steps guide notes that generating those captions locally takes much longer without a GPU, so this is the one feature where a graphics card genuinely matters.

PhotoPrism vs Immich: which should you choose?

Choose PhotoPrism if your photos already sit in folders and you want them indexed, searchable, and pleasant to browse; choose Immich if you want a phone app that automatically backs up your camera roll. They are siblings in the self-hosted media cluster, not rivals — our Immich beginner guide covers the backup-first side, while this guide covers the gallery-first side.

The distinction, as an October 2026 comparison put it: "Immich replaces Google Photos: a phone app backs up your camera roll automatically… PhotoPrism organises a photo library you already have: it indexes folders of files on disk, reads their metadata, puts them on a map, and leaves the files exactly where they were." A second comparison frames it as a simple rule: "If you want to replace Google Photos — including automatic backup from your phone — choose Immich. If your photos already sit on a NAS and you want them indexed, searchable and pleasant to browse, choose PhotoPrism."

One practical consequence: PhotoPrism has no official native mobile app. The official recommendation is to install the Progressive Web App on your phone's home screen and use a third-party sync app — PhotoSync is the one PhotoPrism's own Docker page names — connecting over WebDAV for camera-roll backup.

SQLite vs MariaDB: which database should you pick?

Keep SQLite for a small test library of a few thousand photos; choose MariaDB for anything larger. That is the entire photoprism sqlite vs mariadb decision — and the default compose.yaml already includes MariaDB, so most beginners are on the right database from the first docker compose up.

PhotoPrism officially supports SQLite 3 and MariaDB 10.5.12 or newer; MySQL 8 support has been discontinued, so old tutorials that pair PhotoPrism with MySQL 8 are out of date. SQLite is fine for testing, but it locks frequently under concurrent access — with several people browsing while an index scan runs, you will feel it. MariaDB handles concurrency and scales with the library. The October 2026 release upgraded the database layer and added experimental PostgreSQL support, which suggests the database story will keep evolving, but for a beginner in late 2026 the practical choice is the MariaDB that ships in the compose file.

How do you keep PhotoPrism secure?

You set a strong admin password before the first start, run PhotoPrism behind HTTPS on any public server, and turn on two-factor authentication. PhotoPrism's own docs state the rule plainly: on a public server outside your home network, always run it behind a secure HTTPS reverse proxy such as Traefik or Caddy — otherwise your login credentials travel in clear text.

Start with the password. Never use the default insecure value — and never use any easy-to-guess password — on a publicly accessible server. Remember that after the first start the password can only be changed from the command line: docker compose exec photoprism photoprism passwd [username]. Next, enable two-factor authentication at Settings > Account > 2-Factor Authentication: scan the QR code with an authenticator app, and keep the one-time recovery code it shows you somewhere safe — using that code disables 2FA if you ever lose the device.

If you sync a phone over WebDAV — especially with 2FA turned on — generate a dedicated app password instead of using your main one. Create it at Settings > Account > Apps and Devices, or from the CLI:

docker compose exec photoprism photoprism auth add -n Sync -s "webdav" admin

Scopes keep the blast radius small: "webdav" for a sync client, "*" only when you truly need full access. And if you enable public mode (PHOTOPRISM_AUTH_MODE: "public"), understand what you are doing — it disables authentication entirely, which is only sane behind your own access control.

How do you get photos from your phone into PhotoPrism?

The recommended path is WebDAV: create an app password, connect the PhotoSync app to your PhotoPrism WebDAV endpoint, and uploads trigger an automatic rescan about five minutes later. PhotoPrism's official Docker page lists phone backup via WebDAV as a core feature, and PhotoSync is the third-party app its docs point to.

You can also upload straight from a browser — uploaded files are imported automatically. Once syncing works, install the Progressive Web App on your phone's home screen for an app-like gallery experience; the official first-steps guide lists device sync and the PWA as the final step of a new setup. Either way, remember the direction of the relationship: PhotoPrism is the gallery at the end of the pipe, not the backup tool itself — which is exactly why many people run it next to Immich rather than instead of it.

7 beginner mistakes that break a PhotoPrism install

Every one of these comes from the official docs or from a real install walkthrough — and every one is avoidable in under a minute.

Sources

The facts in this guide were verified on October 31, 2026 from these sources: the PhotoPrism release notes and getting-started docs at docs.photoprism.app (hardware minimums, compose.yaml reference, admin-password and security rules, indexing behavior, AI pipeline, 2FA and app passwords, the October 29, 2026 release notes); the GitHub photoprism/photoprism releases API and repository API (release tag 261029-963b58c50, ~40,381 stars, AGPL-3.0 license, project created January 2018); the official compose file at dl.photoprism.app/docker/compose.yaml (image tags, port 2342, environment variables, MariaDB service); the official user guide pages on first steps, the library, the AI features, and the interface (index vs import, Library > Index, Review queue, WebDAV auto-index, YuNet/SFace on ONNX, search filters); the official Docker Hub page (AI-Powered Photos App positioning, PhotoSync backup); the Marius Hosting PhotoPrism install guides for UGREEN NAS and Synology (corroborating Docker arc, db/import/originals/storage folder layout, UID/GID settings); the It's FOSS PhotoPrism homelab guide (hardware sizing, Docker Compose walkthrough); the peppe8o Raspberry Pi tutorial (default "insecure" password lesson, TensorFlow tagging); the XDA NAS + PhotoPrism build guide (Nextcloud pairing arc); the ssdnodes PhotoPrism vs Immich comparison of October 27, 2026 (the backup-vs-gallery distinction, face recognition in the free Community edition); and the vucense Immich vs PhotoPrism 2026 comparison (the choose-Immich-or-PhotoPrism rule).

Frequently Asked Questions

Is PhotoPrism free?

Yes. PhotoPrism is open-source software under the AGPL-3.0 license, and the Community edition — including face recognition, AI labeling, and the map view — is free. The project's own pages also describe a Plus membership with extras, but nothing in this beginner guide needs it.

Should I use PhotoPrism or Immich?

Use PhotoPrism if your photos already live in folders and you want them indexed, searchable, and pleasant to browse; use Immich if you want a phone app that backs up your camera roll automatically. Many self-hosters run both — Immich as the backup pipe, PhotoPrism as the gallery at the end of it. Our Immich beginner guide covers the other side.

Should I use SQLite or MariaDB with PhotoPrism?

SQLite is fine for testing with a few thousand photos. For a real library — especially with several people browsing — use MariaDB 10.5.12 or newer, which is already included in the official compose file. MySQL 8 support has been discontinued, so ignore old guides that recommend it.

Does PhotoPrism have a phone app?

There is no official native mobile app. The recommended setup is the Progressive Web App installed on your home screen for browsing, plus a third-party sync app like PhotoSync connected over WebDAV for camera-roll backup.

How much RAM does PhotoPrism need?

At least 3 GB of physical memory plus 4 GB of swap, on a 64-bit system with 2 or more CPU cores. Match RAM to the CPU core count, keep the database on an SSD, and never set a hard memory limit on the container.