How to use PhotoPrism as a private AI-powered gallery on your local machine

¿How to use PhotoPrism as a private AI-powered gallery locally? Keeping your photo library under controlWithout relying on the public cloud, it's no longer a dream: with PhotoPrism, you can create a private, AI-powered photo gallery on your own computer or server and browse through years of memories without compromising your privacy. Here's a detailed and practical explanation of how it works, what you need, and how to set it up locally with Docker.

For many, Google Photos is extremely convenient, but in exchange for that convenience there are reasonable doubts about the use of data. If you're concerned about privacy Or if you need to comply with regulations such as GDPR in professional contexts, PhotoPrism is a powerful alternative: automatic organization, AI-powered tags, advanced search, and a workflow designed for large collections, all within your existing infrastructure.

What is PhotoPrism and why use it locally

PhotoPrism is a web application AI-powered photo management (with Google TensorFlow for classification) that recognizes people, objects, colors, and scenes to tag and organize your library. It was created as a self-hosted solution so you can keep your photos and videos at home or on your own server, preserving privacy without sacrificing modern features.

There are several clues in its DNA: compatibility with RAW and classic formats like JPEG or PNG; intelligent indexing with duplicate detection; navigation by timeline, locations, and tags; and a search engine that lets you combine filters by camera, color, date, country, and even mark items as favorites. Everything runs on your machine, with local caches and without relying on third parties for analysis.

The interface is a PWA, so it is installed on the home screen of computers and mobile devices. It works especially well in Chrome, Chromium, Safari, Firefox, and EdgePlease note that playback of certain video and audio codecs (e.g., AAC in H.264) may vary by browser, which is normal on the modern web.

Another differentiating factor is its integration with WebDAV and external services: You can sync from mobile devices with apps like PhotoSyncand also display the gallery with password-protected links that expire. Additionally, if you want maps and location data, PhotoPrism uses a reverse geocoding service and high-privacy maps powered by MapTiler; these resources are designed to minimize exposure and improve caching performance. To learn more, we've included this guide on how Organize your photos with AI without cloud storage: PhotoPrism and local alternatives.

Requirements, hardware and performance

For smooth local use At least two CPU cores, 3 GB of RAM, and a 64-bit system are recommended. Beyond the minimum, it's advisable to match the RAM to the number of cores and, for large libraries, use a local SSD for the database and caches. Indexing is intensive; with an SSD and good swapping, it improves dramatically.

If your server has less than 4 GB of swap, or you set very aggressive memory/swap limits, You might experience unexpected restarts When the indexer needs more resources (this is common with large RAW files, 360 panoramas, or 4K videos), enable or increase the swap space and be patient: with many photos, the initial indexing can take days.

Regarding the database, PhotoPrism supports SQLite 3 and MariaDB 10.5.12 and laterSQLite is easy to get started with, but if you're looking for performance and scalability, MariaDB is a better choice. Support for MySQL 8 has been dropped due to low demand and a lack of features compared to MariaDB. Important tip: avoid using the "latest" tag in the MariaDB image; stick with stable versions that have been thoroughly tested.

Regarding platforms, the app is deployed wherever Docker is available: Linux, macOS and Windows with Docker DesktopIn addition to FreeBSD, Raspberry Pi, and many NAS devices, cloud options exist through PikaPods or DigitalOcean, although we will focus on local solutions here for privacy and control.

Docker installation step by step

If you've never used DockerDon't worry: deploying with Docker Compose is straightforward. The YAML file can be placed in any folder you prefer; first, create a directory for PhotoPrism and save the docker-compose.yml file inside it. The important thing is to clearly define the volumes for originals, storage, and, if desired, import.

These are the three typical setups: originals (read-only or read/write), storage (cache, DB and sidecars) and import (Optional). You can point originals to the folder where you already have your photos. My recommendation: keep storage separate from your photos, so you don't mix the database and cache with your originals.

Basic example of docker-compose with MariaDB and PhotoPrism (you can adapt it to your environment):

version: '3.5'
services:
  mariadb:
    image: 'mariadb:11'
    restart: unless-stopped
    security_opt:
      - 'seccomp:unconfined'
      - 'apparmor:unconfined'
    command: >-
      --innodb-buffer-pool-size=512M
      --transaction-isolation=READ-COMMITTED
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --max-connections=512
      --innodb-rollback-on-timeout=OFF
      --innodb-lock-wait-timeout=120
    environment:
      MARIADB_AUTO_UPGRADE: '1'
      MARIADB_INITDB_SKIP_TZINFO: '1'
      MARIADB_DATABASE: 'photoprism'
      MARIADB_USER: 'photoprism'
      MARIADB_PASSWORD: 'cambia-esto'
      MARIADB_ROOT_PASSWORD: 'cambia-esto'
    volumes:
      - './database:/var/lib/mysql'

  photoprism:
    image: 'photoprism/photoprism:latest'
    depends_on:
      - mariadb
    stop_grace_period: 10s
    security_opt:
      - 'seccomp:unconfined'
      - 'apparmor:unconfined'
    ports:
      - '2342:2342'
    environment:
      PHOTOPRISM_ADMIN_USER: 'admin'
      PHOTOPRISM_ADMIN_PASSWORD: 'cambia-esto'
      PHOTOPRISM_AUTH_MODE: 'password'
      PHOTOPRISM_SITE_URL: 'http://localhost:2342/'
      PHOTOPRISM_DEFAULT_TLS: 'true'
      PHOTOPRISM_DATABASE_DRIVER: 'mysql'
      PHOTOPRISM_DATABASE_SERVER: 'mariadb:3306'
      PHOTOPRISM_DATABASE_NAME: 'photoprism'
      PHOTOPRISM_DATABASE_USER: 'photoprism'
      PHOTOPRISM_DATABASE_PASSWORD: 'cambia-esto'
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_JPEG_QUALITY: 85
      PHOTOPRISM_DISABLE_WEBDAV: 'false'
      PHOTOPRISM_DISABLE_TENSORFLOW: 'false'
      PHOTOPRISM_DETECT_NSFW: 'false'
      PHOTOPRISM_SIDECAR_JSON: 'true'
      PHOTOPRISM_SIDECAR_YAML: 'true'
    working_dir: '/photoprism'
    volumes:
      - '~/Pictures:/photoprism/originals'
      - './storage:/photoprism/storage'
      - './import:/photoprism/import'

With the file ready, open a terminal in that folder and run: docker-compose up -dThe first initialization downloads images and creates the database; give it a few minutes. Then, it starts indexing with docker compose exec photoprism photoprism indexTo be updated in the future: docker compose pull photoprism, docker compose stop photoprism y docker compose up -d –no-deps photoprism.

Default credentials: admin username and the password you define in environment variables. Remember to change weak passwords as soon as you log in for the first time. If you're going to import a lot of material, it's worth disabling ML functions during the initial indexing and then enabling them later.

Secure access, local domains, and reverse proxy

If you are going to expose the service outside your network, Always put it after HTTPS with a reverse proxy like Traefik or Caddy. Without TLS, everything travels in plain text and could be intercepted. Maintaining privacy is part of the plan: use valid certificates and redirect HTTP to HTTPS.

To access locally with a domain like photoprism.localhost without a port, you have two options: map a standard port on the host (for example, 80:2342, for local use only) or configure Traefik to listen on 80 and route to the service on 2342. Ensure that the container labels include the router, entrypoint, and internal service port. A typical pattern with Traefik would be to define the Host rule, the web entrypoint, and point the service port to 2342.

Another key point is the firewall: allows incoming connections to the ports you use (web and https) and outbound to the geocoding API and Docker when necessary. If you block those outbound connections, the maps and places won't work properly.

Organization, AI, and features that make a difference

PhotoPrism works with a powerful catalog and sidecars; You can write metadata in JSON and YAML Alongside your originals, so it doesn't depend solely on the database. Classification with TensorFlow (faces, objects, scenes, and NSFW) speeds up searches, and deciding whether to mark sensitive photos as private is as easy as enabling a setting.

To maintain performance, you can adjust thumbnail quality and size, video codecs, bitrate limits, and rescaling. FFmpeg is configured by variables And, if your hardware supports it, you can delegate to Intel QSV, Nvidia, Apple, or VAAPI for accelerated transcoding. With just a few clicks, you can go from a basic workflow to one tailored to your system.

Navigation is agile: timeline, albums, tags, favorites, and places. The advanced search panel It lets you filter by camera, dates, countries, colors, or people. If you're coming from chaotic libraries, duplicate detection and metadata normalization help you bring order painlessly.

On mobile devices, there is no official app, but you can use the PWA or sync with WebDAV using apps like PhotoSync. The PWA is very practicalIt installs like a native app, saving you from having to use a browser every time. However, the experience on Android TV or Google TV is limited, as with most solutions in this sector; the most reliable option remains using a browser on a laptop connected to the TV if you want to comfortably view photos with your family.

Who benefits most from PhotoPrism

Professional photographers With thousands of RAW files, you'll find a powerful ally: indexing, searching by lens or camera, duplicate detection, and sidecars to avoid altering the original. Having your collection controlled, tagged, and consolidated saves hours of work in the medium term.

To graphic designers and creativesColor-coded labels and object tags help you quickly locate visual inspiration. Viewing by moments and using a timeline helps you retrieve ideas and materials without losing track.

In the real estate sector, real estate agents They can categorize properties by location, date, or tags, and share albums with protected links that expire. Privacy is key here, and having control of the server is a plus.

Digital marketing teams They appreciate an organized library of assets, with filters for campaigns, dates, and countries. Multi-user support and the use of sidecars make it easy to avoid breaking the originals and to share internal collections without exposing them externally.

To travelers, digital archivists and developersThe advantages range from interactive maps to the ability to integrate the gallery with other services via WebDAV. If compliance is also a concern, keeping the data on your own infrastructure helps you with GDPR and internal policies.

Popular alternatives and how they fit in

Immich is hitting hardIt's very reminiscent of Google Photos, with a seamless timeline, key-based favorites, mobile syncing, and semantic search by concepts or colors. Importing from Google Takeout is incredibly easy with tools like Immich-Go. On the downside, the Android TV app is limited; for TV sessions, a laptop browser is preferable.

In the field of productivity suites, Nextcloud Photos and the Memories plugin They offer a solid option if you already use Nextcloud. The Recognize app provides facial recognition, and Imaginary and Preview Generator speed up previews. The interface is functional, although quick actions like marking favorites aren't as immediate as in other options.

PhotoStructure It offers a different approach, with a home screen that displays a random selection of photos to help you rediscover your archive. It's fast and fresh, but its Plus mode unlocks features like favorites and facial recognition, which might scare off those looking for everything free and local.

Piwigo, Photoview, Lychee or Photonix They cover diverse scenarios: simple galleries, basic recognition, or organization by tags. If your priority is the timeline and quick shortcuts, they might fall short. LibrePhotos looks very promising on paper, but its implementation can be more manual and it doesn't always run smoothly on modest computers.

To Plex has launched Plex Photos Currently in beta for iOS, Android, and web, Plex is an interesting option if you're already a Plex user, although it currently lacks a polished native Android TV app. Ente, on the other hand, has open-sourced its code and boasts end-to-end encryption; it looks very promising, even with desktop clients, although its self-hosting requires some technical know-how.

Frequently Asked Questions for Docker Beginners

Where do I put the YAML file?In any folder you like. The important thing is to run the Docker Compose commands from that directory so it reads the correct YAML. Keep docker-compose.yml and subfolders like storage, database, and import together so you have everything readily available.

Should I mount my current photo folder? Yes, map your photos folder to /photoprism/originals. If you prefer not to grant write permissions, you can mount it read-only, but you'll lose in-place metadata editing capabilities; PhotoPrism also avoids touching the original files with sidecars.

Where do the database and cache go? It's best to store them outside your photos folder, in a separate path that you map to /photoprism/storage (and, if you're using MariaDB, to ./database in the DBMS container). This way you don't mix caches and databases with your original files.

How to mount a folder in DockerIn the volumes key, use the format host_path:container_path. For example, ~/Pictures:/photoprism/originals. Verify the permissions of the user running the container; if necessary, use the PHOTOPRISM_UID and PHOTOPRISM_GID variables or the user directive to align permissions.

Do we need Traefik or Caddy? Only do this if you want automatic TLS, clean domains and paths, or if you're exposing the service to the internet. Locally, mapping port 2342 is sufficient. If you're using Traefik, define the host, the web entrypoint, and the internal port 2342 for the service; this way you can access it with photoprism.localhost without adding :2342.

Support, updates and community

The project aims to be the most privacy-friendly option And it has a dynamic roadmap. They aim for a zero-defect policy, and therefore don't set firm dates for new features: the pace also depends on funding and community support. If it's a good fit for you, becoming a member accelerates the development of what interests you most.

To resolve any doubts, you have Discussions on GitHub and community chatSilver, Gold, and Platinum members can also contact technical support. Before opening a bug report, check the troubleshooting checklists; often the problem is a local configuration issue and can be resolved quickly.

In updates, you can automate with Watchtower If you're comfortable with that, fine; otherwise, it's better to use a pull, stop, and up process when a stable version is released. In serious environments, use fixed versions and avoid using the latest version, both in PhotoPrism and MariaDB, to ensure controlled updates.

If you're concerned about maps and reverse geocoding, PhotoPrism and MapTiler These services offer a very high level of privacy. Their use is covered by the project, with caching to improve performance and prevent your queries from being overexposed.

Finally, remember the obvious but essential: Making backups is not optionalIf you manage family memories or client materials, the responsibility is yours. Back up your database, storage, and, most importantly, your original files in at least two different locations. Avoid cheap USB drives or slow network folders for your database.

At this stage, PhotoPrism He has earned the position As a robust solution for having your own local Google Photos: AI for sorting, SSD speed, sidecars for preserving originals, and a polished PWA. If you prioritize enjoyment over cataloging, you might be drawn to alternatives like Immich for their interface; if meticulous organization is your thing, PhotoPrism shines. Whatever your needs, with a good Docker Compose setup, sufficient swap space, HTTPS for internet access, and backups, you'll have a solid system set up for years to come.