# PhotoPrism ships a development compose file, a develop branch and date-hash tags

> PhotoPrism is a Go photo and video library you run with Docker, index with machine learning, and query through a typed filter syntax. The repository you would clone is not the one you deploy: its default branch is develop, its compose.yaml is labelled for tests only, and its releases are named by date and commit hash rather than by version number.

**photoprism/photoprism** — GitHub describes it as AI-Powered Photos App 🌈💎✨. The repository metadata lists Go as its primary language. The metadata lists the NOASSERTION license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/photoprism/photoprism
- Website: https://www.photoprism.app
- Stars: 40,258 · Forks: 2,329
- Language: Go
- License: NOASSERTION
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/photoprism-photoprism

## The compose file in the repository is labelled do not use in production

The first line of the root compose.yaml is a warning, not a comment of convenience: it says the file is for test and development only, and points at a developer setup guide. What it starts is a development harness:

```yaml
  services:
    photoprism:
      build:
        context: .
        dockerfile: ${DOCKERFILE:-Dockerfile}
      image: photoprism/photoprism:develop
      depends_on:
        - mariadb
        - dummy-webdav
        - dummy-oidc
      security_opt:
        - seccomp:unconfined
        - apparmor:unconfined
```

Read those five lines together. The image tag is `develop`, not a release. The dependencies are a MariaDB service plus two stubs named dummy-webdav and dummy-oidc, which exist so tests have something to talk to. And both seccomp and apparmor are set to unconfined, which is a reasonable thing to do for a container that needs a debugger attached and an unreasonable thing to do for a container holding your photographs.

Cloning the repository and running compose gets you a test rig. The supported install path is documented separately, on docs.photoprism.app, and the README describes it as needing a web browser and Docker.

## Nine compose files are the deployment matrix

The root carries compose.yaml plus compose.armv7.yaml, compose.intel.yaml, compose.latest.yaml, compose.local.yaml, compose.mariadb.yaml, compose.mysql.yaml, compose.nvidia.yaml and compose.preview.yaml. That list is the honest feature matrix for a self-hosted app, because each file is a decision the operator has to make.

Two of them are architecture. armv7 targets 32-bit ARM, which the README otherwise says is outside the supported multi-arch image, so the file exists for the case where 32-bit is all you have. intel exists to pin the x86 image rather than take whatever the manifest resolves to on the day you pull.

The rest are choices with real consequences. mariadb and mysql pick the metadata database. nvidia adds a GPU, which matters because indexing is the expensive part. preview tracks the development channel, and latest tracks the newest stable image rather than a version you chose. Only after you have picked from all of these do you have a configuration, which is why people who want a set-and-forget photo library sometimes look elsewhere.

## Port 2342 is HTTP, 2443 is TLS, and both start on loopback

The dev compose file publishes four ports and binds all of them to 127.0.0.1 unless you override it:

```yaml
    ports:
      - "${SERVICES_BIND_HOST:-127.0.0.1}:2342:2342"   # HTTP (default)
      - "${SERVICES_BIND_HOST:-127.0.0.1}:2443:2443"   # TLS (default)
      - "${SERVICES_BIND_HOST:-127.0.0.1}:2343:2343"   # HTTP (acceptance tests)
      - "${SERVICES_BIND_HOST:-127.0.0.1}:40000:40000" # Go debugger
```

The loopback default is the right call and it is also why remote access is the recurring question for this project. To reach an instance from a phone or another machine you have to set `SERVICES_BIND_HOST` to an address or interface, and that single variable decides whether your library is on your LAN or on the internet.

Note the fourth line. A Go debugger port is in the same list as the HTTP and TLS ports, and the file also raises `shm_size` to 2gb and wires seven Traefik hostnames, including ones for a vector database and an OIDC provider. This is a test harness that publishes its internals on purpose, which is exactly why it should never be the file you copy into production.

## Search is a typed filter language, and s2: is an open location code

The library URLs in the README are the documentation for the query syntax. `q=mp:4` is a resolution filter, `q=color:red` is a colour filter, `q=mono%3Atrue` is a chroma filter, `q=type%3Alive` selects Live Photos, and `q=s2:47a85a63f764` is a location filter.

That last one is worth decoding. The go.mod requires `google/open-location-code` and `golang/geo`, along with `paulmach/go.geojson`, and a plus code like `47a85a63f764` is an open location code, the short alphanumeric reference standard used for places without street addresses. So the location filter in that URL is not a geohash from a proprietary source, it is a dependency in the module graph, and the same value can be typed by hand from a Plus Code someone sends you.

The practical consequence is that the query string is an interface. These URLs are bookmarkable, shareable and scriptable, and a filter can be handed to someone else as text. Few self-hosted photo managers give you that, and it is the feature most likely to survive a UI redesign.

## Releases are named by date and commit, not by version

Three releases appear on the feed: 260919-28c46a116 from September 19, 2026, 260728-bbde8f452 from July 28, 2026, and 260601-a7d098548 from June 1, 2026. The pattern is a six-digit date followed by a nine-character commit hash, with the human date spelled out in the tag description.

There is a `.semver` file at the repository root, and the docs distinguish stable releases from a development preview, so a version exists somewhere behind these tags. But a semver range does not match a tag called 260919-28c46a116, and that has a direct effect on your infrastructure: an automated updater that speaks semver has nothing to resolve here, so pinning and upgrading are both manual.

The default branch is `develop`, not master or main, which is the other half of the same story. The last push was on 2026-09-29, so the branch is being worked on; the released artifacts are cut from somewhere else, and the README does not say from where.

## The supported install needs a browser and Docker, and tar.gz is the exception

The documented self-hosted community edition install is described as needing a web browser and Docker, and it is available for Mac, Linux and Windows. Images are published as a multi-arch build for 64-bit AMD, Intel and ARM, which is the line that puts Raspberry Pi and Apple Silicon users on the same installation steps as everyone else.

The escape hatch is named explicitly. A getting started FAQ entry covers installing without Docker, and the answer is the tar.gz packages published for Linux. That is a different operating model rather than a variant: with tar.gz you own the service unit, the port, the upgrade path and the log rotation, instead of handing all of that to a container runtime.

One detail from the Dockerfile worth knowing before you build anything yourself: the default base is `photoprism/develop:260921-resolute`, and the alternatives are listed in comments, from `photoprism/develop:noble` for Ubuntu 24.04 LTS down to `photoprism/develop:bullseye` for Debian 11, with an `armv7` build among them. Which base you pick is part of the install, not an afterthought.

## Membership gates features, and the privacy claim is a README statement

The funding section is unusually direct. PhotoPrism describes itself as completely self-funded and independent, states it will never sell your data, and says your data is not shared with Google, Amazon, Microsoft or Apple unless you intentionally upload files to one of their services. Members get additional features, named as access to interactive world maps, and a private chat room with the team. Payment runs through Stripe with credit card or SEPA, or through Patreon with PayPal, more currencies and a monthly or annual choice, and GitHub Sponsors supporters can link their existing account.

Read the feature list against that. The overview advertises six high-resolution world maps and a privacy-preserving geocoding service, and the membership section says interactive world maps are a member feature. So the headline list and the paywalled list overlap, and the README does not draw the line explicitly.

The other place to look is the repository itself, which carries a `.telemetry` directory at the root. A privacy promise is a statement in a README; the telemetry directory is the code. If the promise is load-bearing for what you put in the library, that directory is the one to read before you import anything.

## Where the money goes is the difference from the usual alternative

Immich is the other self-hosted photo and video manager people evaluate alongside this one, and it is a legitimate choice for anyone who wants a mobile-first app with automatic background backup and nothing else to think about. The architectural difference is visible in the module lists: PhotoPrism's backend is Go, with image structure parsers for JPEG, PNG, TIFF, HEIC and Photoshop files plus `mandykoh/prism` for RAW, and its frontend is a separate JavaScript workspace, since the root package.json is private and declares `workspaces` of `frontend` alone.

The difference that decides it for a household is the funding model, and here the two projects answer differently. PhotoPrism's README is explicit that the project is funded by membership and that members receive extra features, which means the feature list and the free tier are not the same set and you have to check which is which. Payment handling adds a second wrinkle for self-hosters: a Stripe, SEPA, Patreon and GitHub Sponsors arrangement is a vendor relationship that exists alongside your deployment, whatever your privacy settings say about your photos.

On licensing, the repository's license field does not resolve and the README's licence badge points at a documentation page rather than at the LICENSE file in the root, so read that file before you expose an instance to anyone.

## Conclusion

Adopt PhotoPrism if you want one Docker container to index a mixed RAW and video library, expose it over WebDAV as well as HTTP, and search it with a filter language you can put in a bookmark. Do not adopt it expecting a free feature set equal to the README's feature list, because membership is where the interactive world maps and the team chat live, and do not deploy from the repository's own compose.yaml, which is labelled for test and development only. Verify three things: that the tags you pin are the ones your instance was built from, since releases are named 260919-28c46a116 rather than by version, that the port you expose is 2342 for HTTP or 2443 for TLS and not the debugger port the dev file also publishes, and that whatever the telemetry directory at the root actually does matches the privacy statement in the README before you point it at family photos.

## FAQ

### Is PhotoPrism free?

The self-hosted community edition is free to run, and the project states it is completely self-funded and independent, promising never to sell your data. Members receive additional features, named as access to interactive world maps, plus a private chat room, and pay through Stripe, Patreon or a linked GitHub Sponsors account.

### What is a PhotoPrism?

PhotoPrism is described as an AI-powered, privacy-first app for browsing, organizing and sharing photos and videos, written in Go. It tags, searches and labels media automatically based on content and location, and recognises the faces of people you add.

### how to install photoprism

The documented install is the self-hosted community edition, and all it requires is a web browser and Docker, with images published as a multi-arch build for 64-bit AMD, Intel and ARM. Step-by-step instructions are on docs.photoprism.app, and a getting started FAQ entry covers installing without Docker using the tar.gz packages published for Linux.

### how to install photoprism on windows

The community edition is available for Mac, Linux and Windows, and because it runs in a container the host operating system mainly decides which Docker install you use. Raspberry Pi and Apple Silicon users are given the same installation steps as everyone else on the multi-arch image.

### how to install photoprism on docker

Docker is the supported route, and the root compose.yaml is explicitly labelled for test and development only, building the image photoprism/photoprism:develop with seccomp and apparmor unconfined. The production compose configuration is documented separately on docs.photoprism.app rather than taken from the repository root.

### how to use photoprism

Browse and search the library through the web interface or the installable progressive web app, and combine search filters for labels, location, resolution, color, chroma and quality. The README also describes WebDAV access from Windows Explorer and Apple Finder for opening, editing and deleting files, and background phone backup through a compatible native app such as PhotoSync.

## Sources

- [Official documentation](https://www.photoprism.app)
- [Official README](https://github.com/photoprism/photoprism#readme)
- [Project repository](https://github.com/photoprism/photoprism)
- [Release notes](https://github.com/photoprism/photoprism/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/photoprism-photoprism