To connect a new instance to your membership account, log in with the admin user[^1] that is automatically created during setup (see your configuration files or the app store documentation),[^2] then follow these steps once your membership is activated as shown in the screenshot:
(1) In the main navigation click on *Support Our Mission*. If you do not see this link, you can manually navigate to */library/upgrade* in the browser toolbar.
(2) Click *Register* to sign in on our website and receive a code to connect your account.
(3) Finally, please restart your instance for the changes to take effect. You should now see your membership level when you open the *About* page. Thank you very much!
### Troubleshooting 
## Developer Guide
Our [Developer Guide](https://docs.photoprism.app/developer-guide/) contains all the information you need to get started as a developer. It guides you from [setting up your development environment](https://docs.photoprism.app/developer-guide/setup/) and [creating pull requests](https://docs.photoprism.app/developer-guide/pull-requests/) to [running tests](https://docs.photoprism.app/developer-guide/tests/) and [adding translations](https://docs.photoprism.app/developer-guide/translations-weblate/). Multiple subsections provide details on specific features and links to external resources for further information.
> [!NOTE]
> **Want to learn more about our development practices?** Our approach relies heavily on agile methodologies with a high degree of automation and continuous integration. Many of the best practices we use and have proven to be effective are described in [Quality and Best Practices](https://docs.photoprism.app/developer-guide/code-quality/).
## GitHub Repository
The source code, including automated tests and a readme file that gives a [short and concise overview](https://github.com/photoprism/photoprism/blob/develop/README.md) of the project, can be found on GitHub at 
### How many years has the product been sold to companies?
Our software was [first released in 2020](https://docs.photoprism.app/release-notes/) and is [freely available](https://github.com/photoprism/photoprism) under an [open source license](https://docs.photoprism.app/license/agpl/). As such, it is used by a considerable number of companies. To better meet the needs of professional users, we subsequently launched [PhotoPrism® Pro](/teams/#compare) in 2022, which provides [teams and organizations](/teams/#compare) with additional [configuration options](/pro/kb/), [enterprise support plans](/pro/support/), and [customer services](/pro/support/#professional-services).
### What is the difference between your public license and a license agreement?
A key difference between the Public License and our Pro License Agreement is that you get access to additional support and configuration options, as well as the right to customize functionality to your needs without having to publicly disclose your changes. We are also working to optimize the standard configuration, feature set, and scalability of [PhotoPrism® Pro](/teams/#compare) to meet the needs of professional users.
### What is the difference between your Pro and Enterprise offerings?
[PhotoPrism® Enterprise](/enterprise/) offers all the features of the [Pro Edition](/teams/#compare) with additional product and service options designed to meet the needs of large-scale enterprises and organizations. Individual pricing for our Enterprise offering depends on business size, number of users, and [support level](/pro/support/). Please [contact us](/contact/) for a custom quote.
### How many organisations are using your product?
There are currently more than 40,000 active installations, growing daily. Because we [respect the privacy](/privacy/) of our users, we do not have detailed information about whether these are run by individuals, businesses, or other organizations. [PhotoPrism® Pro](/teams/#compare), our version for professional users, is currently used by a number of news agencies, NGOs as well as governments.
### How many clients have stopped using the product?
For our paid [PhotoPrism+ Membership](/editions/#compare), we currently have a 2.7% churn rate. For SaaS, the [average churn rate](https://www.profitwell.com/recur/all/average-churn-rate) is around 5%, and a "good" churn rate is considered 3% or less.
### Are you prepared to guarantee the renewal price?
As stated in our [Terms of Service](/terms/) and in the [PhotoPrism® Pro License Agreement](/pro/license/), prices are subject to change and may be adjusted to account for currency fluctuations, inflation, new features and enhancements.
Changes will take effect at the next renewal of the Subscription Term. We intend to avoid unexpected changes and announce price adjustments in a timely manner.
### Where can I learn more about your team?
PhotoPrism was founded by Michael Mayer and Theresa Gresch. Prior to founding PhotoPrism, Michael spent more than two decades advising startups and corporate clients such as Deutsche Telekom, Mercedes-Benz and many others. Theresa holds a master's degree in neurobiology. Before she started working on PhotoPrism, she used her organizational skills as a freelance product manager at startups and creative agencies.
### Do you organize user forums or conferences?
Conferences are not currently planned. We do, however, operate a large number of private and [public forums](https://link.photoprism.app/discussions) and [chats](https://link.photoprism.app/chat) that our active community uses to network, share ideas, and help each other.
### How can we ensure that developments based on our requirements are not shared?
Purchasing a [commercial license](/pro/license/) gives you the right to customize the functionality to your needs without having to publicly disclose your changes. When PhotoPrism provides professional services to you for a fee, our [Terms of Service](/terms/) include an agreement to maintain the confidentiality of trade secrets and confidential or proprietary information.
In any event, PhotoPrism retains all proprietary rights in its software, services, documentation and all derivative works thereof, however created, and all intellectual property rights incorporated in or related to the foregoing. All rights not expressly provided by us to you under a license agreement or public license are reserved.
## Technology, Development, and Documentation {#technology}
### What range of documentation do you provide?
Our [knowledge base](/kb/) provides you with an overview of [all available documentation](/kb/docs/). You can find the sources of our user and developer guides on GitHub at [github.com/photoprism/photoprism-docs](https://github.com/photoprism/photoprism-docs).
### Is your source code available on demand?
The source code, including automated tests and a [readme file](https://github.com/photoprism/photoprism/blob/develop/README.md) that gives a short and concise overview of the project, can be found on GitHub at [github.com/photoprism/photoprism](https://github.com/photoprism/photoprism).
### Are you following software development best practices?
Our approach relies heavily on agile methodologies with a high degree of automation and continuous integration. Many of the best practices we use and have proven to be effective are described in [Quality and Best Practices](https://docs.photoprism.app/developer-guide/code-quality/), which is part of the [Developer Guide](https://docs.photoprism.app/developer-guide/).
### What technologies is your software based on?
**Frontend:** [Progressive Web App (PWA)](https://web.dev/progressive-web-apps/) based on [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), and [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS)
**Backend:** [Go](https://go.dev/) and [Google TensorFlow](https://www.tensorflow.org/)
**Operating Systems:** [Linux](https://www.debian.org/), [macOS](https://www.apple.com/macos/), and [FreeBSD](https://www.freebsd.org/) natively; plus all [platforms that support Docker](https://docs.docker.com/get-started/get-docker/), such as Windows
**Databases:** [MariaDB](https://mariadb.org/), [SQLite](https://www.sqlite.org/); support for [PostgreSQL](https://www.postgresql.org/) is planned without a specific release date yet
### Do you provide any mobile apps?
At the moment, PhotoPrism does not have a native mobile app that can be installed through an official app store. However, our [Progressive Web App (PWA)](https://docs.photoprism.app/user-guide/pwa/) offers an almost native app-like experience. You can conveniently install it on the home screen of all major operating systems and mobile devices.
To [sync photos and videos](https://docs.photoprism.app/user-guide/sync/mobile-devices/) on your phone, you can use any app that supports [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/). We recommend [PhotoSync](/partners/), which is available for Android and iOS.
### Which photo and video file formats are supported?
Our [knowledge base](/kb/) provides you with an overview of [all supported file formats](/kb/file-formats/).
### How many and which APIs do you have?
Based on our [public source code](https://github.com/photoprism/photoprism), GoDoc automatically generates [an API documentation for developers](https://pkg.go.dev/github.com/photoprism/photoprism).
## Scalability Limits {#scalability}
### Is there an explicit file size limit?
JPEG images are generally supported up to a maximum size of 30,000 pixels. Note, however, that high-resolution panoramic images may require additional swap space and/or physical memory beyond the [recommended minimum](https://docs.photoprism.app/getting-started/#system-requirements).
The file size limit in megabytes and the resolution limit in megapixels can be changed using parameters, so these depend on your individual configuration.
### What is the maximum number of files that are allowed or can be managed?
There is no explicit limit to the number of files, except for the limitations imposed by the underlying database, the server's file system, and the size of the variables used as record identifiers, i.e. in the billions.
The number of files is primarily limited by the storage available. Practical usability also relies on the server's CPU and memory, while the time needed for indexing depends on the size of your files and their formats. We recommend that you test the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license.
### Is your solution load-balanced?
Our Enterprise customers can receive support for setting up PhotoPrism in a cluster configuration on an individual basis.
### How many users can use your software simultaneously?
There is no predefined technical limit for the number of concurrent users. PhotoPrism generally scales well with the number of CPU cores. However, you should keep in mind that the available server resources can be significantly reduced when the backend is busy indexing or importing a large amount of files.
You can limit the number of indexing workers to reduce the server load depending on your individual needs. It is also possible to change the file size limit in megabytes and the resolution limit in megapixels.
If you plan to connect your instance to the public Internet, where the number of users can fluctuate greatly and some users may be accessing the service from remote locations with high latency, we additionally recommend configuring a *Content Delivery Network (CDN)* like [bunny.net](https://link.photoprism.app/bunny-cdn), as this can effectively reduce server load and improve the user experience:
When in doubt, you are welcome to test the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license.
### How much data is cached by the database?
When using MariaDB, the [InnoDB buffer pool](https://docs.photoprism.app/getting-started/troubleshooting/performance/#mariadb) serves as a cache for data and indexes. It is a key component for optimizing MariaDB performance. Its size should be as large as possible to keep frequently used data in memory and reduce disk I/O - typically the biggest bottleneck.
### Can you provide detailed performance test results?
You may find performance test results attached to specific [GitHub issues](https://github.com/photoprism/photoprism/issues) or [pull requests](https://github.com/photoprism/photoprism/pulls), for example, to document the [result of a performance optimization](https://github.com/photoprism/photoprism/pull/2433). However, we do not currently publish performance test results in a form that would be suitable for the general public or as marketing material.
When in doubt, we recommend that you test performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license.
## Future Functionality {#functionality}
### What product changes are planned for the coming months and years?
Our [Project Roadmap](https://link.photoprism.app/roadmap) shows what tasks are in progress and which features are likely to be implemented next. Be aware that we have a [zero-bug policy](https://docs.photoprism.app/known-issues/) and do our best to help users when they need support or have other questions. This comes at a price, as we can't give exact release dates for new features.
As stated in our [Terms of Service](/terms/), you are welcome to ask for implementation of new features, enhancements, or other changes in the software, services or documentation. Our team will carefully consider your requests, but is not legally obligated to implement the changes you request. If your purchase depends on the availability of a certain feature, we recommend to wait until it has been released.
### How far into the future are you planning?
We focus on outcomes, optimize [effectiveness before efficiency](https://docs.photoprism.app/developer-guide/code-quality/#effectiveness-efficiency), and plan as much ahead as necessary to meet our goals and commitments. To reduce risk, overhead, and the need to schedule manual work, our approach relies heavily on agile methodologies with a high degree of automation and continuous integration. Many of the best practices we use and have proven to be effective are described in [Quality and Best Practices](https://docs.photoprism.app/developer-guide/code-quality/), which is part of the [Developer Guide](https://docs.photoprism.app/developer-guide/).
### What are the tasks and priorities in your daily work? {#priorities}
Our priorities are (1) providing bug fixes, security improvements, and support, (2) maintaining core functionality, e.g. ensuring compatibility and performance, providing documentation, (3) adding core functionality, e.g. file type support, search filters, config options, (4) working on other features such as multi-user, scalability, and hardware acceleration.
## Getting Updates {#updates}
### How frequently do you release updates?
Fully functional development previews with the latest features and improvements are provided very frequently, up to several times a day.
New stable versions that have been thoroughly tested are made available up to several times a month. Since quality is our top priority, this depends on what we are currently working on and whether we consider it ready for release.
### How do you resolve defects and provide corrections?
PhotoPrism follows a zero-bug policy, which means that we do our best to fix any issues we learn about. Corrections will then be made available with the next stable release. Fully functional development previews with the latest features and improvements are made available very frequently, up to several times a day.
If resolving an issue is not immediately possible, for example due to dependencies on third-party libraries or other applications, or because it is a specific use case that we do not currently support, you can find a note and available workarounds in our [Known Issues](https://docs.photoprism.app/known-issues/).
## Support Options {#support}
### Do you have a web-based support service?
Our business customers [enjoy email and chat support](/pro/support/) directly from our team. It is available during regular business hours from Monday to Friday on a best-effort basis.
We also offer remote assistance via phone and video call upon request. In addition, customers can choose to receive [Enterprise or Gold Support](/pro/support/), which guarantee a first response within 8 business hours, depending on severity.
### What happens on bank holidays?
Please [contact us](/contact/) to receive a custom quote for extended support on weekends and holidays.
## Data, Backups, and Reports {#data}
### Do you work with standardized fields and formats?
We rely on open standards and make our [source code available](https://github.com/photoprism/photoprism) to ensure a high level of compatibility and transparency. Our [Knowledge Base](/kb/) contains an overview of the [supported Exif, XMP, IPTC, and DCMI tags](/kb/metadata/) and their internal field names.
### How does your product allow us to create reports?
Currently, no business reporting engine is integrated. Security audits and many other technical reports, such as active browser sessions or the status of database migrations, can be viewed through the command line interface and exported as CSV or Markdown. You can also access the SQL database directly to generate reports on specific metrics using standard products designed for this purpose. If needed, we offer consulting services to help you set up a custom solution.
### Can the database be modified by means other than the user interface?
Yes, you can modify the index database and create backup copies using standard database tools compatible with MariaDB.
### Do you provide the possibility to anonymize copies of the database?
No. If required, we offer consulting services to help you implement a custom solution.
### What tools do you recommend for alternate data mining?
We do not recommend any particular tools. If needed, we offer consulting services to help you implement a custom solution.
### Do you have documents defining the referential elements of the database?
Information about the index database schema is provided as an entity-relationship diagram, [Mermaid.js](https://mermaid-js.github.io/) markup, and MariaDB-compatible SQL:
- [Developer Guide](https://docs.photoprism.app/developer-guide/database/schema/)
- [Database Schema](https://github.com/photoprism/photoprism/tree/develop/internal/entity/schema)
The [entity models](https://github.com/photoprism/photoprism/tree/develop/internal/entity) as part of our [public source code](https://github.com/photoprism/photoprism) also serve as a form of documentation that can be well used by many developers. Feel free to [contact us with your specific requirements](/contact/) if you need additional technical documentation.
### Is data archiving part of the solution?
PhotoPrism provides commands to back up and restore the database. It is your responsibility to back up your data and make sure it is kept safe. Backing up media files is possible with commercially available file backup tools. We do not recommend any particular tools at this time.
### Does your product identify unused data over a period of time?
Our solution does not currently provide analytics that allow you to identify media content that you have not downloaded or viewed over a period of time. However, commands are available to remove stale index entries and unused thumbnail files.
### In the event of an outage, how would you recommend to recover without a loss of data?
It is your responsibility to manage your own infrastructure, provide a sufficient level of redundancy, back up your data and ensure that it is kept secure.
## Privacy and Security
### How does your product support GDPR and Data Protection? {#privacy}
Our [Privacy Policy](/privacy/) explains what information we collect, how we use it, and under what circumstances we may share it. Read our [GDPR Compliance Statement](/privacy/gdpr/) to learn more about the rights you have as a resident of the European Economic Area ("EEA") and our ongoing commitment to user privacy and the General Data Protection Regulation ("GDPR"). We also provide a wide range of other [documentation and resources](/kb/docs/) to help you evaluate our products and services in terms of privacy.
### Does your software depend on external services or is it completely self-contained?
As explained in our [Privacy Policy](/privacy/#section-7), reverse geocoding and interactive world maps depend on retrieving the necessary information from [us](/contact/) and [MapTiler AG](https://www.maptiler.com/contacts/), headquartered in Switzerland. Both services are provided with a very high level of privacy and confidentiality.
Your use of these services is [fully covered by us](https://docs.photoprism.app/getting-started/faq/#are-the-keys-for-using-interactive-world-maps-provided-free-of-charge). Depending on your usage, this can save you thousands of dollars every month, since other providers generally charge usage-based fees and often don't allow you to cache the data they provide, compromising performance and your privacy with unnecessary requests.
Should you wish to operate one or both of these services on your own premises, we can set up such a [fully autonomous solution](#fully-autonomous-solution) for you, provided you are prepared to cover the initial setup costs as well as ongoing maintenance fees for content licenses and updates.
*Other open source applications sometimes use the free map tile service operated by [openstreetmap.org](https://operations.osmfoundation.org/policies/tiles/). In this case, [their usage](https://operations.osmfoundation.org/policies/tiles/) and [privacy policies](https://wiki.osmfoundation.org/wiki/Privacy_Policy) apply, which means that your request data is stored and used to [create publicly available reports](https://planet.openstreetmap.org/tile_logs/). This is different from our approach, which focuses on [your privacy](/privacy/) and user experience.*
### What are the initial costs for setting up self-hosted reverse geocoding and world maps? {#fully-autonomous-solution}
Setting up this infrastructure on premises is particularly suitable for enterprise customers such as large companies or government agencies that require an exceptionally high level of confidentiality.
Professional Services provided directly by our core team are [priced at € 1499.00 per day](/teams/#compare). The exact amount will depend on the specific environment in which you want us to set up these services, your scalability and security requirements, as well as how much and what type of documentation you want us to provide to your team. Server hardware should have [at least 128 GB of RAM and a 4 TB SSD](https://nominatim.org/release-docs/latest/admin/Installation/#hardware).
License prices for self-hosted world maps can be found, for example, at [www.maptiler.com/data/pricing/](https://www.maptiler.com/data/pricing/).
### What capabilities are built-in to protect from issues with the GDPR?
Self-hosting is the easiest way to stay in control and protect your privacy. Data that never leaves your private network can't be collected by anyone, including us. It is your responsibility to evaluate your use of our software for compliance with your privacy policy and to update it as necessary.
### Please explain the built-in security of your product? {#security}
PhotoPrism uses common best practices to protect the application and its users, such as storing passwords in a way that cannot be reversed and setting recommended HTTP security headers. In addition, PhotoPrism® Pro offers session monitoring, a security audit log, and role-based user access.
However, please note that virtually all file format parsers have vulnerabilities that have not been discovered yet. For example, the [release notes of all Apple products](https://support.apple.com/en-us/HT212602) contain a long list of fixes for bugs that allow execution of arbitrary code with kernel privileges. This is a known risk that can affect you even if your server is not directly connected to the Internet.
We recommend running our application in a container with limited host access, as this is an easy way to improve security without compromising performance and usability. When combined with a virtual machine or dedicated server, this provides optimal protection against malicious code accessing other applications and data. Additionally, please make sure that only trusted users can upload files, manage them via WebDAV or modify them directly in the file system.
If you install our software on a public server outside your own network or if you connect your private server to the public Internet, we additionally recommend using a firewall, such as [OPNsense®](https://shop.opnsense.com/), to ensure the highest level of security.
### Has your product ever been exposed to DDOS attacks and what was the result?
PhotoPrism Pro includes a rate limiter for HTTP requests and failed login attempts. We additionally recommend using a firewall, such as [OPNsense®](https://shop.opnsense.com/), to ensure the highest level of security.
### Which tools are required for monitoring and alerting the product?
You can use the GET /api/v1/status API endpoint to perform health checks in combination with any standard monitoring solution. You may also want to monitor CPU and memory usage during indexing so you can add more resources if needed. At this time, we do not recommend any particular tools. If needed, we offer consulting services to help you set up a custom solution.
---
# Config Options
URL: https://www.photoprism.app/kb/config-options/
> Get an overview of the global config variables and command-line flags available in PhotoPrism.
### Authentication
| Environment | CLI Flag | Default | Description |
|:-------------------------------------------------|:------------------------|:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_AUTH_MODE | --auth-mode | password | authentication `MODE` (public, password) |
| PHOTOPRISM_ADMIN_USER, PHOTOPRISM_ADMIN_USERNAME | --admin-user | admin | `USERNAME` of the superadmin account that is created on first startup |
| PHOTOPRISM_ADMIN_PASSWORD | --admin-password | | initial `PASSWORD` of the superadmin account (8-72 characters) |
| PHOTOPRISM_PASSWORD_LENGTH | --password-length | 8 | minimum password `LENGTH` in characters |
| PHOTOPRISM_LOGIN_INFO | --login-info | | custom login footer info `TEXT` *plus* |
| PHOTOPRISM_OIDC_URI | --oidc-uri | | issuer `URI` for single sign-on via OpenID Connect, e.g. https://accounts.google.com |
| PHOTOPRISM_OIDC_CLIENT | --oidc-client | | client `ID` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_SECRET | --oidc-secret | | client `SECRET` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_SCOPES | --oidc-scopes | openid email profile address | client authorization `SCOPES` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_PROMPT | --oidc-prompt | | authorization `PROMPT` for single sign-on via OpenID Connect (login, select_account, consent) |
| PHOTOPRISM_OIDC_PROVIDER | --oidc-provider | | custom identity provider `NAME`, e.g. Google |
| PHOTOPRISM_OIDC_ICON | --oidc-icon | | custom identity provider icon `URI` |
| PHOTOPRISM_OIDC_REDIRECT | --oidc-redirect | false | automatically redirects unauthenticated users to the configured identity provider |
| PHOTOPRISM_OIDC_REGISTER | --oidc-register | false | allows new users to create an account when they sign in with OpenID Connect |
| PHOTOPRISM_OIDC_LOGOUT | --oidc-logout | false | ends the provider session on sign-out via OpenID Connect RP-initiated logout |
| PHOTOPRISM_OIDC_USERNAME | --oidc-username | preferred_username | preferred username `CLAIM` for new OpenID Connect users (preferred_username, name, nickname, email) |
| PHOTOPRISM_OIDC_WEBDAV | --oidc-webdav | false | allows new OpenID Connect users to use WebDAV when they have a role that allows it |
| PHOTOPRISM_DISABLE_OIDC | --disable-oidc | false | disables single sign-on via OpenID Connect, even if an identity provider has been configured |
| PHOTOPRISM_SESSION_MAXAGE | --session-maxage | 1209600 | session expiration time in `SECONDS`, doubled for accounts with 2FA (-1 to disable) |
| PHOTOPRISM_SESSION_TIMEOUT | --session-timeout | 604800 | session idle time in `SECONDS`, doubled for accounts with 2FA (-1 to disable) |
| PHOTOPRISM_SESSION_CACHE | --session-cache | 900 | session cache duration in `SECONDS` (60-3600) |
| PHOTOPRISM_DOWNLOAD_TOKEN | --download-token | | shared static `TOKEN` accepted for permanent download URLs without identifying a session (leave blank to accept signed tokens only) |
| PHOTOPRISM_DOWNLOAD_TOKEN_MAXAGE | --download-token-maxage | 3600 | signed download token lifetime in `SECONDS` (minimum 900) |
| PHOTOPRISM_PREVIEW_TOKEN | --preview-token | | shared static `TOKEN` for thumbnail and video streaming URLs (leave blank for an automatic value) |
### Logging
| Environment | CLI Flag | Default | Description |
|:---------------------|:------------|:--------|:-------------------------------------------------------------------|
| PHOTOPRISM_LOG_LEVEL | --log-level | info | log message verbosity `LEVEL` (trace, debug, info, warning, error) |
| PHOTOPRISM_PROD | --prod | false | disables debug mode and only logs startup warnings and errors |
| PHOTOPRISM_DEBUG | --debug | false | enables debug mode for development and troubleshooting |
| PHOTOPRISM_TRACE | --trace | false | enables trace mode to display all debug and trace logs |
### Storage
| Environment | CLI Flag | Default | Description |
|:----------------------------|:-------------------|:-----------------------------|:---------------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_STORAGE_PATH | --storage-path | | writable storage `PATH` for sidecar, cache, and database files |
| PHOTOPRISM_STORAGE_FREE | --storage-free | -1 | minimum `PERCENT` (1-99) of free storage required for indexing, importing, and uploads, -1 disables the check |
| PHOTOPRISM_CONFIG_PATH | --config-path | | config storage `PATH` or options.yml filename, values in this file override CLI flags and environment variables if present |
| PHOTOPRISM_DEFAULTS_YAML | --defaults-yaml | /etc/photoprism/defaults.yml | loads default config values from `FILENAME` if it exists, does not override CLI flags or environment variables |
| PHOTOPRISM_ORIGINALS_PATH | --originals-path | | storage `PATH` of your original media files (photos and videos) |
| PHOTOPRISM_ORIGINALS_LIMIT | --originals-limit | 1000 | maximum size of media files in `MB` (1-100000; -1 to disable) |
| PHOTOPRISM_RESOLUTION_LIMIT | --resolution-limit | 150 | maximum resolution of media files in `MEGAPIXELS` (1-900; -1 to disable) |
| PHOTOPRISM_USERS_PATH | --users-path | users | relative `PATH` to create base and upload subdirectories for users |
| PHOTOPRISM_IMPORT_PATH | --import-path | | base `PATH` from which files can be imported to originals *optional* |
| PHOTOPRISM_IMPORT_DEST | --import-dest | | relative originals `PATH` in which files should be imported by default *optional* |
| PHOTOPRISM_IMPORT_ALLOW | --import-allow | | restricts imports to these file types (comma-separated list of `EXTENSIONS`; leave blank to allow all) |
| PHOTOPRISM_UPLOAD_NSFW | --upload-nsfw | false | allows uploads that might be offensive (when disabled, files flagged by the NSFW model are rejected before indexing) |
| PHOTOPRISM_UPLOAD_ALLOW | --upload-allow | | restricts uploads to these file types (comma-separated list of `EXTENSIONS`; leave blank to allow all) |
| PHOTOPRISM_UPLOAD_ARCHIVES | --upload-archives | false | allows upload of zip archives (will be extracted before import) |
| PHOTOPRISM_UPLOAD_LIMIT | --upload-limit | 1000 | maximum total size of uploaded files in `MB` (1-100000; -1 to disable) |
| PHOTOPRISM_CACHE_PATH | --cache-path | | custom cache `PATH` for sessions and thumbnail files *optional* |
| PHOTOPRISM_TEMP_PATH | --temp-path | | temporary file `PATH` *optional* |
| PHOTOPRISM_ASSETS_PATH | --assets-path | | assets `PATH` containing static resources like icons, models, and translations |
| PHOTOPRISM_MODELS_PATH | --models-path | | custom model assets `PATH` where computer vision models are located |
### Sidecar Files
| Environment | CLI Flag | Default | Description |
|:------------------------|:---------------|:--------|:-------------------------------------------------------|
| PHOTOPRISM_SIDECAR_PATH | --sidecar-path | | custom relative or absolute sidecar `PATH` *optional* |
| PHOTOPRISM_SIDECAR_YAML | --sidecar-yaml | true | creates YAML sidecar files to back up picture metadata |
### Usage
| Environment | CLI Flag | Default | Description |
|:-----------------------|:--------------|:--------|:------------------------------------------------------------------|
| PHOTOPRISM_USAGE_INFO | --usage-info | false | displays storage usage information in the user interface |
| PHOTOPRISM_FILES_QUOTA | --files-quota | 0 | maximum total size of all indexed files in `GB` (0 for unlimited) |
### Backup
| Environment | CLI Flag | Default | Description |
|:---------------------------|:------------------|:--------|:--------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_BACKUP_PATH | --backup-path | | custom base `PATH` for creating and restoring backups *optional* |
| PHOTOPRISM_BACKUP_SCHEDULE | --backup-schedule | daily | backup `SCHEDULE` in cron format (e.g. "0 12 \* \* \*" for daily at noon) or at a random time (daily, weekly) |
| PHOTOPRISM_BACKUP_RETAIN | --backup-retain | 3 | `NUMBER` of index backups to keep (-1 to keep all) |
| PHOTOPRISM_BACKUP_DATABASE | --backup-database | true | enables regular backups based on the configured schedule |
| PHOTOPRISM_BACKUP_ALBUMS | --backup-albums | true | enables the use of YAML files for backing up album metadata |
### Indexing
| Environment | CLI Flag | Default | Description |
|:---------------------------------------------|:------------------|:--------|:--------------------------------------------------------------------------------------------------|
| PHOTOPRISM_INDEX_WORKERS, PHOTOPRISM_WORKERS | --index-workers | auto | maximum `NUMBER` of indexing workers, or 'auto' to derive from the available CPU cores |
| PHOTOPRISM_INDEX_SCHEDULE | --index-schedule | | indexing `SCHEDULE` in cron format (e.g. "@every 3h" for every 3 hours; "" to disable) |
| PHOTOPRISM_WAKEUP_INTERVAL | --wakeup-interval | 15m0s | `TIME` between facial recognition, file sync, and metadata worker runs (1-86400s) |
| PHOTOPRISM_AUTO_INDEX | --auto-index | 300 | delay before automatically indexing files in `SECONDS` when uploading via WebDAV (-1 to disable) |
| PHOTOPRISM_AUTO_IMPORT | --auto-import | -1 | delay before automatically importing files in `SECONDS` when uploading via WebDAV (-1 to disable) |
### Feature Flags
| Environment | CLI Flag | Default | Description |
|:----------------------------------|:-------------------------|:--------|:--------------------------------------------------------------------------------------------------|
| PHOTOPRISM_READONLY | --read-only | false | disables features that require write permission for the originals folder |
| PHOTOPRISM_EXPERIMENTAL | --experimental | false | enables new features that may be incomplete or unstable |
| PHOTOPRISM_DISABLE_FRONTEND | --disable-frontend | false | disables the web user interface so that only the service API endpoints are accessible |
| PHOTOPRISM_DISABLE_SETTINGS | --disable-settings | false | disables the settings frontend and related API endpoints, e.g. in combination with public mode |
| PHOTOPRISM_DISABLE_BACKUPS | --disable-backups | false | prevents database and album backups as well as YAML sidecar files from being created |
| PHOTOPRISM_DISABLE_RESTART | --disable-restart | false | prevents admins from restarting the server through the user interface |
| PHOTOPRISM_DISABLE_WEBDAV | --disable-webdav | false | prevents other apps from accessing PhotoPrism as a shared network drive |
| PHOTOPRISM_DISABLE_MCP | --disable-mcp | false | disables the Model Context Protocol (MCP) API endpoint for AI agent integrations |
| PHOTOPRISM_DISABLE_PLACES | --disable-places | false | disables interactive world maps and reverse geocoding |
| PHOTOPRISM_DISABLE_TENSORFLOW | --disable-tensorflow | false | disables face recognition with TensorFlow *deprecated* |
| PHOTOPRISM_DISABLE_FACES | --disable-faces | false | disables face detection and recognition (requires TensorFlow) |
| PHOTOPRISM_DISABLE_CLASSIFICATION | --disable-classification | false | disables all image classification and label generation |
| PHOTOPRISM_DISABLE_FFMPEG | --disable-ffmpeg | false | disables video transcoding and thumbnail extraction with FFmpeg |
| PHOTOPRISM_DISABLE_EXIFTOOL | --disable-exiftool | false | disables metadata extraction with ExifTool (required for full Video, Live Photo, and XMP support) |
| PHOTOPRISM_DISABLE_SIPS | --disable-sips | false | disables file conversion using the sips command under macOS |
| PHOTOPRISM_DISABLE_DARKTABLE | --disable-darktable | false | disables conversion of RAW images with Darktable |
| PHOTOPRISM_DISABLE_RAWTHERAPEE | --disable-rawtherapee | false | disables conversion of RAW images with RawTherapee |
| PHOTOPRISM_DISABLE_IMAGEMAGICK | --disable-imagemagick | false | disables conversion of image files with ImageMagick |
| PHOTOPRISM_DISABLE_HEIFCONVERT | --disable-heifconvert | false | disables conversion of HEIC images with libheif |
| PHOTOPRISM_DISABLE_RSVGCONVERT | --disable-rsvgconvert | false | disables conversion of SVG graphics with librsvg *plus* |
| PHOTOPRISM_DISABLE_VECTORS | --disable-vectors | false | disables vector graphics support *plus* |
| PHOTOPRISM_DISABLE_JPEGXL | --disable-jpegxl | false | disables JPEG XL file format support |
| PHOTOPRISM_DISABLE_RAW | --disable-raw | false | disables indexing and conversion of RAW images |
| PHOTOPRISM_RAW_PRESETS | --raw-presets | false | enables custom user presets when converting RAW images (reduces performance) |
| PHOTOPRISM_EXIF_BRUTEFORCE | --exif-bruteforce | false | performs a brute-force search if no Exif headers were found |
### Customization
| Environment | CLI Flag | Default | Description |
|:----------------------------|:-------------------|:-----------|:---------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_DEFAULT_LOCALE | --default-locale | en | default user interface language `CODE` |
| PHOTOPRISM_DEFAULT_TIMEZONE | --default-timezone | Local | default time zone `NAME`, e.g. for scheduling backups |
| PHOTOPRISM_DEFAULT_THEME | --default-theme | | default user interface theme `NAME` |
| PHOTOPRISM_PLACES_LOCALE | --places-locale | local | location details language `CODE`, e.g. en, de, or local |
| PHOTOPRISM_APP_NAME | --app-name | | app `NAME` when installed as a Progressive Web App (PWA) |
| PHOTOPRISM_APP_MODE | --app-mode | standalone | app display `MODE` (fullscreen, standalone, minimal-ui, browser) |
| PHOTOPRISM_APP_ICON | --app-icon | | home screen app `ICON` (logo, app, crisp, mint, bold, square, bloom, flower, ring, glass, neon, rainbow) |
| PHOTOPRISM_APP_COLOR | --app-color | #19191a | app background and splash screen `COLOR` |
| PHOTOPRISM_LEGAL_INFO | --legal-info | | legal information `TEXT`, displayed in the page footer |
| PHOTOPRISM_LEGAL_URL | --legal-url | | legal information `URL` |
| PHOTOPRISM_WALLPAPER_URI | --wallpaper-uri | | login screen background image `URI` |
### Site Information
| Environment | CLI Flag | Default | Description |
|:----------------------------|:-------------------|:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_SITE_URL | --site-url | http://localhost:2342/ | canonical site `URL` used in generated links and to determine HTTPS/TLS (scheme://host[:port]) |
| PHOTOPRISM_SITE_AUTHOR | --site-author | | site `OWNER` shown in the author meta tag |
| PHOTOPRISM_SITE_NAME | --site-name | | short `NAME` for identifying this instance within a cluster *optional* |
| PHOTOPRISM_SITE_TITLE | --site-title | | main `TITLE` shown in the web interface and meta tags |
| PHOTOPRISM_SITE_CAPTION | --site-caption | AI-Powered Photos App | short `CAPTION` or tagline shown alongside the title |
| PHOTOPRISM_SITE_DESCRIPTION | --site-description | | longer `DESCRIPTION` shown in SEO and social meta tags *optional* |
| PHOTOPRISM_SITE_FAVICON | --site-favicon | | custom favicon `FILENAME` for web browsers *optional* |
| PHOTOPRISM_SITE_PREVIEW | --site-preview | | sharing preview image `URL` |
| PHOTOPRISM_CDN_URL | --cdn-url | | content delivery network `URL` |
| PHOTOPRISM_CDN_VIDEO | --cdn-video | false | streams videos over the specified CDN |
| PHOTOPRISM_CORS_ORIGIN | --cors-origin | | origin `URL` from which browsers are allowed to perform cross-origin requests (leave blank to disable or use * to allow all) |
| PHOTOPRISM_CORS_HEADERS | --cors-headers | Accept, Accept-Ranges, Content-Disposition, Content-Encoding, Content-Range, Location | one or more `HEADERS` that browsers should see when performing a cross-origin request |
| PHOTOPRISM_CORS_METHODS | --cors-methods | GET, HEAD, OPTIONS | one or more `METHODS` that may be used when performing a cross-origin request |
### Networking
| Environment | CLI Flag | Default | Description |
|:--------------------------------|:-----------------------|:------------------|:--------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_HTTPS_PROXY | --https-proxy | | proxy server `URL` to be used for outgoing connections *optional* |
| PHOTOPRISM_HTTPS_PROXY_INSECURE | --https-proxy-insecure | false | ignores invalid HTTPS certificates when using a proxy |
| PHOTOPRISM_TRUSTED_PLATFORM | --trusted-platform | | trusted client IP header `NAME`, e.g. when running behind a cloud provider load balancer |
| PHOTOPRISM_TRUSTED_PROXY | --trusted-proxy | 172.16.0.0/12 | `CIDR` ranges or IPv4/v6 addresses from which reverse proxy headers can be trusted, separated by commas |
| PHOTOPRISM_PROXY_CLIENT_HEADER | --proxy-client-header | X-Forwarded-For | proxy client IP header `NAME`, e.g. X-Forwarded-For, X-Client-IP, X-Real-IP, or CF-Connecting-IP |
| PHOTOPRISM_PROXY_PROTO_HEADER | --proxy-proto-header | X-Forwarded-Proto | proxy protocol header `NAME` |
| PHOTOPRISM_PROXY_PROTO_HTTPS | --proxy-proto-https | https | forwarded HTTPS protocol `NAME` |
| PHOTOPRISM_SERVICES_CIDR | --services-cidr | | comma-separated `CIDR` ranges or IPs allowed for outbound service connections, e.g. 172.18.0.0/16 |
### Web Server
| Environment | CLI Flag | Default | Description |
|:--------------------------------|:-----------------------|:------------|:----------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_DISABLE_TLS | --disable-tls | false | disables HTTPS/TLS even if the site URL starts with https:// and a certificate is available |
| PHOTOPRISM_DEFAULT_TLS | --default-tls | false | uses a self-signed HTTPS/TLS certificate if no other certificate is available |
| PHOTOPRISM_TLS_CERT | --tls-cert | | public HTTPS certificate `FILENAME` (.crt), ignored for Unix domain sockets |
| PHOTOPRISM_TLS_KEY | --tls-key | | private HTTPS key `FILENAME` (.key), ignored for Unix domain sockets |
| PHOTOPRISM_DISABLE_STS | --disable-sts | false | disables HTTP Strict-Transport-Security (STS) header |
| PHOTOPRISM_STS_SECONDS | --sts-seconds | 31536000 | `TIME` for the browser to remember that the site is to be accessed only via HTTPS (0 to disable) *plus* |
| PHOTOPRISM_STS_SUBDOMAINS | --sts-subdomains | false | rule applies to all subdomains as well *plus* |
| PHOTOPRISM_STS_PRELOAD | --sts-preload | false | submit to Google's HSTS preload service *plus* |
| PHOTOPRISM_AUTH_LIMIT | --auth-limit | 60 | maximum number of consecutive invalid access `TOKENS` from a single IP *plus* |
| PHOTOPRISM_AUTH_INTERVAL | --auth-interval | 10s | average `DURATION` between invalid access tokens from a single IP (0-86400s) *plus* |
| PHOTOPRISM_LOGIN_LIMIT | --login-limit | 10 | maximum number of consecutive failed `LOGINS` from a single IP *plus* |
| PHOTOPRISM_LOGIN_INTERVAL | --login-interval | 1m0s | average `DURATION` between failed logins from a single IP (0-86400s) *plus* |
| PHOTOPRISM_IPS_LIMIT | --ips-limit | 3 | maximum number of malicious request `ATTEMPTS` before a client IP is blocked (-1 to disable) *plus* |
| PHOTOPRISM_IPS_INTERVAL | --ips-interval | 1h0m0s | average `DURATION` between malicious request attempts from a single IP (0-86400s) *plus* |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_CTO | --http-cto | nosniff | HTTP X-Content-Type-Options `HEADER` *plus* |
| PHOTOPRISM_HTTP_COOP | --http-coop | same-origin | HTTP Cross-Origin-Opener-Policy (COOP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_REFERRER_POLICY | --http-referrer-policy | same-origin | HTTP Referrer-Policy `HEADER` *plus* |
| PHOTOPRISM_HTTP_FRAME_OPTIONS | --http-frame-options | DENY | HTTP X-Frame-Options `HEADER` *plus* |
| PHOTOPRISM_HTTP_MODE | --http-mode | | Web server `MODE` (debug, release, test) |
| PHOTOPRISM_HTTP_COMPRESSION | --http-compression | | Web server compression `METHODS` as a comma-separated preference list (e.g. "zstd,gzip"; supported: gzip, zstd, none) |
| PHOTOPRISM_HTTP_HEADER_TIMEOUT | --http-header-timeout | 15s | timeout for reading request headers as `DURATION` |
| PHOTOPRISM_HTTP_HEADER_BYTES | --http-header-bytes | 1048576 | maximum request header size in `BYTES` |
| PHOTOPRISM_HTTP_IDLE_TIMEOUT | --http-idle-timeout | 3m0s | timeout for idle keep-alive connections as `DURATION` |
| PHOTOPRISM_HTTP_CACHE_PUBLIC | --http-cache-public | false | allows static content to be cached by a CDN or caching proxy |
| PHOTOPRISM_HTTP_CACHE_MAXAGE | --http-cache-maxage | 2592000 | time in `SECONDS` until cached content expires |
| PHOTOPRISM_HTTP_VIDEO_MAXAGE | --http-video-maxage | 21600 | time in `SECONDS` until cached videos expire |
| PHOTOPRISM_HTTP_HOST | --http-host | 0.0.0.0 | Web server `IP` address or Unix domain socket, e.g. unix:/var/run/photoprism.sock?force=true&mode=660 |
| PHOTOPRISM_HTTP_PORT | --http-port | 2342 | Web server port `NUMBER`, ignored for Unix domain sockets |
| PHOTOPRISM_HTTP_HOSTNAME | --http-hostname | | serve requests for this `HOSTNAME` only *plus* |
### Database Connection
| Environment | CLI Flag | Default | Description |
|:-------------------------------|:----------------------|:-----------|:-------------------------------------------------------------------|
| PHOTOPRISM_DATABASE_DRIVER | --database-driver | sqlite | database `DRIVER` (sqlite, mysql) |
| PHOTOPRISM_DATABASE_DSN | --database-dsn | | database connection `DSN` (sqlite file, optional for mysql) |
| PHOTOPRISM_DATABASE_NAME | --database-name | photoprism | database schema `NAME` |
| PHOTOPRISM_DATABASE_SERVER | --database-server | | database `HOST` incl. port, e.g. "mariadb:3306" (or socket path) |
| PHOTOPRISM_DATABASE_USER | --database-user | photoprism | database user `NAME` |
| PHOTOPRISM_DATABASE_PASSWORD | --database-password | | database user `PASSWORD` |
| PHOTOPRISM_DATABASE_TIMEOUT | --database-timeout | 15 | timeout in `SECONDS` for establishing a database connection (1-60) |
| PHOTOPRISM_DATABASE_CONNS | --database-conns | 0 | maximum `NUMBER` of open database connections |
| PHOTOPRISM_DATABASE_CONNS_IDLE | --database-conns-idle | 0 | maximum `NUMBER` of idle database connections |
### File Conversion
| Environment | CLI Flag | Default | Description |
|:-----------------------------------------------------------------|:--------------------------|:-----------------------------------------|:-----------------------------------------------------------------------------------------------|
| PHOTOPRISM_FFMPEG_BIN | --ffmpeg-bin | ffmpeg | FFmpeg `COMMAND` for video transcoding and thumbnail extraction |
| PHOTOPRISM_FFMPEG_ENCODER | --ffmpeg-encoder | libx264 | FFmpeg AVC video encoder `NAME` |
| PHOTOPRISM_FFMPEG_SIZE | --ffmpeg-size | 4096 | encoding resolution limit in `PIXELS` (720-15360) |
| PHOTOPRISM_FFMPEG_QUALITY | --ffmpeg-quality | 50 | encoding `QUALITY` (1-100, where 100 is almost lossless) |
| PHOTOPRISM_FFMPEG_BITRATE | --ffmpeg-bitrate | 60 | bitrate `LIMIT` in Mbps for forced transcoding of non-AVC videos (1-960; -1 to disable) |
| PHOTOPRISM_FFMPEG_PRESET | --ffmpeg-preset | fast | FFmpeg compression `PRESET` when using an encoder that supports it, e.g. fast, medium, or slow |
| PHOTOPRISM_FFMPEG_DEVICE | --ffmpeg-device | | FFmpeg device `PATH` when using a hardware encoder that supports it as parameter |
| PHOTOPRISM_FFMPEG_MAP_VIDEO | --ffmpeg-map-video | `0:v:0` | transcoding video stream `MAP` |
| PHOTOPRISM_FFMPEG_MAP_AUDIO | --ffmpeg-map-audio | `0:a:0?` | transcoding audio stream `MAP` |
| PHOTOPRISM_FFMPEG_EXCLUDE, PHOTOPRISM_FFMPEG_BLACKLIST | --ffmpeg-exclude | magy, vfw | container and codec `FORMATS` not to be processed by FFmpeg, separated by commas |
| PHOTOPRISM_EXIFTOOL_BIN | --exiftool-bin | exiftool | ExifTool `COMMAND` for extracting metadata |
| PHOTOPRISM_SIPS_BIN | --sips-bin | sips | Sips `COMMAND` for media file conversion *macOS only* |
| PHOTOPRISM_SIPS_EXCLUDE, PHOTOPRISM_SIPS_BLACKLIST | --sips-exclude | avif, avifs, thm | file `EXTENSIONS` not to be used with Sips *macOS only* |
| PHOTOPRISM_DARKTABLE_BIN | --darktable-bin | darktable-cli | Darktable CLI `COMMAND` for RAW to JPEG conversion |
| PHOTOPRISM_DARKTABLE_EXCLUDE, PHOTOPRISM_DARKTABLE_BLACKLIST | --darktable-exclude | thm | file `EXTENSIONS` not to be used with Darktable |
| PHOTOPRISM_DARKTABLE_CACHE_PATH | --darktable-cache-path | | custom Darktable cache `PATH` |
| PHOTOPRISM_DARKTABLE_CONFIG_PATH | --darktable-config-path | | custom Darktable config `PATH` |
| PHOTOPRISM_RAWTHERAPEE_BIN | --rawtherapee-bin | rawtherapee-cli | RawTherapee CLI `COMMAND` for RAW to JPEG conversion |
| PHOTOPRISM_RAWTHERAPEE_EXCLUDE, PHOTOPRISM_RAWTHERAPEE_BLACKLIST | --rawtherapee-exclude | dng, thm | file `EXTENSIONS` not to be used with RawTherapee |
| PHOTOPRISM_IMAGEMAGICK_BIN | --imagemagick-bin | convert | ImageMagick CLI `COMMAND` for image file conversion |
| PHOTOPRISM_IMAGEMAGICK_EXCLUDE, PHOTOPRISM_IMAGEMAGICK_BLACKLIST | --imagemagick-exclude | heif, heic, heics, avif, avifs, jxl, thm | file `EXTENSIONS` not to be used with ImageMagick |
| PHOTOPRISM_HEIFCONVERT_BIN | --heifconvert-bin | heif-dec | libheif HEIC image conversion `COMMAND` |
| PHOTOPRISM_RSVGCONVERT_BIN | --rsvgconvert-bin | rsvg-convert | librsvg SVG graphics conversion `COMMAND` *plus* |
| PHOTOPRISM_HEIFCONVERT_ORIENTATION | --heifconvert-orientation | keep | Exif `ORIENTATION` of images generated with libheif (keep, reset) |
### Preview Images
| Environment | CLI Flag | Default | Description |
|:-------------------------------|:----------------------|:--------|:-----------------------------------------------------------------------------|
| PHOTOPRISM_THUMB_LIBRARY | --thumb-library | auto | image processing `LIBRARY` to be used for generating thumbnails (auto, vips) |
| PHOTOPRISM_THUMB_COLOR | --thumb-color | auto | standard color `PROFILE` for thumbnails (auto, preserve, srgb, none) |
| PHOTOPRISM_THUMB_SIZE | --thumb-size | 1920 | maximum size of pre-generated thumbnails in `PIXELS` (720-15360) |
| PHOTOPRISM_THUMB_SIZE_UNCACHED | --thumb-size-uncached | 7680 | maximum size of thumbnails generated on demand in `PIXELS` (720-15360) |
| PHOTOPRISM_THUMB_UNCACHED | --thumb-uncached | false | generates missing thumbnails on demand (high memory and cpu usage) |
### Image Quality
| Environment | CLI Flag | Default | Description |
|:------------------------|:---------------|:--------|:------------------------------------------------------------------|
| PHOTOPRISM_JPEG_QUALITY | --jpeg-quality | 83 | higher values increase the image `QUALITY` and file size (25-100) |
| PHOTOPRISM_JPEG_SIZE | --jpeg-size | 15360 | maximum size of generated JPEG images in `PIXELS` (720-30000) |
| PHOTOPRISM_PNG_SIZE | --png-size | 15360 | maximum size of generated PNG images in `PIXELS` (720-30000) |
### Computer Vision
| Environment | CLI Flag | Default | Description |
|:---------------------------|:------------------|:------------|:----------------------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_VISION_YAML | --vision-yaml | | computer vision model configuration `FILENAME` *optional* |
| PHOTOPRISM_VISION_API | --vision-api | false | enables the computer vision API endpoints under /api/v1/vision (requires authorization) |
| PHOTOPRISM_VISION_URI | --vision-uri | | vision service base `URI`, e.g. https://example.com/api/v1/vision (leave blank to disable) |
| PHOTOPRISM_VISION_KEY | --vision-key | | vision service access `TOKEN` *optional* |
| PHOTOPRISM_VISION_SCHEDULE | --vision-schedule | | vision worker `SCHEDULE` for background processing (e.g. "0 12 \* \* \*" for daily at noon) or at a random time (daily, weekly) |
| PHOTOPRISM_VISION_FILTER | --vision-filter | public:true | vision worker search `FILTER` applied to scheduled runs (same syntax as photoprism vision run) |
| PHOTOPRISM_DETECT_NSFW | --detect-nsfw | false | flags newly added pictures as private if they might be offensive (uses the configured NSFW model; built-in TensorFlow by default) |
| PHOTOPRISM_XMP_FACES | --xmp-faces | false | imports face regions and names from XMP metadata as people markers |
### Face Recognition
> [!NOTE]
> A reasonable range for the similarity distance is between 0.60 and 0.85, with higher values resulting in more aggressive clustering and more false positives. To cluster a smaller number of faces, reduce the core to 3 or 2 similar faces. After changing any of the clustering parameters, it is **strongly recommended** that you run the "photoprism faces reset" command in a terminal to remove existing clusters and mappings, as otherwise inconsistencies may result in unexpected behavior or errors.
We recommend that only advanced users change these parameters:
| Environment | CLI Flag | Default | Description |
|:---------------------------------|:------------------------|:--------|:------------------------------------------------------------------------|
| PHOTOPRISM_FACE_ENGINE | --face-engine | auto | face detection engine `NAME` (auto, onnx) |
| PHOTOPRISM_FACE_ENGINE_THREADS | --face-engine-threads | 0 | face detection thread `COUNT` (0 uses half the available CPU cores) |
| PHOTOPRISM_FACE_SIZE | --face-size | 25 | minimum size of faces in `PIXELS` (20-10000) |
| PHOTOPRISM_FACE_SCORE | --face-score | 9 | minimum face `QUALITY` score (1-100) |
| PHOTOPRISM_FACE_OVERLAP | --face-overlap | 42 | face area overlap threshold in `PERCENT` (1-100) |
| PHOTOPRISM_FACE_CLUSTER_SIZE | --face-cluster-size | 60 | minimum size of automatically clustered faces in `PIXELS` (20-10000) |
| PHOTOPRISM_FACE_CLUSTER_SCORE | --face-cluster-score | 20 | minimum `QUALITY` score of automatically clustered faces (1-100) |
| PHOTOPRISM_FACE_CLUSTER_CORE | --face-cluster-core | 4 | `NUMBER` of faces forming a cluster core (1-100) |
| PHOTOPRISM_FACE_CLUSTER_DIST | --face-cluster-dist | 0.64 | similarity `DISTANCE` of faces forming a cluster core (0.1-1.5) |
| PHOTOPRISM_FACE_CLUSTER_RADIUS | --face-cluster-radius | 0.42 | maximum cluster `RADIUS` accepted for automatic matches (0.1-1.5) |
| PHOTOPRISM_FACE_COLLISION_DIST | --face-collision-dist | 0.05 | minimum collision discrimination `DISTANCE` (0.01-1) |
| PHOTOPRISM_FACE_EPSILON_DIST | --face-epsilon-dist | 0.01 | collision tolerance `DELTA` appended to max match distances (0.001-0.1) |
| PHOTOPRISM_FACE_MATCH_DIST | --face-match-dist | 0.4 | similarity `OFFSET` for matching faces with existing clusters (0.1-1.5) |
| PHOTOPRISM_FACE_SKIP_CHILDREN | --face-skip-children | false | skips automatic matching of child face embeddings |
| PHOTOPRISM_FACE_ALLOW_BACKGROUND | --face-allow-background | false | allows matching of probable background embeddings |
### Daemon Mode
If you start the server as a *daemon* in the background, you can additionally specify a filename for the log and the process ID:
| Environment | CLI Flag | Default | Description |
|:------------------------|:---------------|:--------|:-----------------------------------------|
| PHOTOPRISM_PID_FILENAME | --pid-filename | | process id `FILENAME` *daemon-mode only* |
| PHOTOPRISM_LOG_FILENAME | --log-filename | | server log `FILENAME` *daemon-mode only* |
### Docker Image ###
The following variables are used by our Docker images only and have no effect otherwise:
| Environment | Default | Description |
|--------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_UID | 0 | run as a non-root user after initialization (supported: 0, 33, 50-99, 500-600, 900-1250, and 2000-2100) |
| PHOTOPRISM_GID | 0 | run with a specific group id after initialization, can optionally be used together with `PHOTOPRISM_UID` (supported: 0, 33, 44, 50-99, 105, 109, 115, 116, 500-600, 900-1250, and 2000-2100) |
| PHOTOPRISM_UMASK | 0002 | [file-creation mode](https://linuxize.com/post/umask-command-in-linux/) (default: u=rwx,g=rwx,o=rx) |
| PHOTOPRISM_INIT | https tensorflow | run/install on first startup (common options: [update tensorflow https intel gpu davfs yt-dlp](https://github.com/photoprism/photoprism/blob/develop/scripts/dist/Makefile)) |
| PHOTOPRISM_DISABLE_CHOWN | false | disable updating storage permissions via chmod and chown on startup |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Setup Guide](https://docs.photoprism.app/getting-started/)
- [PhotoPrism® Config Files](https://docs.photoprism.app/getting-started/config-files/)
- [PhotoPrism® Knowledge Base](/kb/)
---
# Documentation
URL: https://www.photoprism.app/kb/docs/
> Find user guides, developer guides, legal information, and more.
## Getting Started
Step-by-step [installation instructions](https://docs.photoprism.app/getting-started/) for our self-hosted community edition can be found in [Getting Started](https://docs.photoprism.app/).
All you need is a Web browser and Docker to run the server. It is available for Mac, Linux, and Windows.
**Need help?** Common issues can be quickly diagnosed and solved using the troubleshooting checklists we provide at [docs.photoprism.app/getting-started/troubleshooting](https://docs.photoprism.app/getting-started/troubleshooting/). You can also find helpful background information on [Known Issues](https://docs.photoprism.app/known-issues/) and learn what workarounds are available.
## User Guide
Visit [docs.photoprism.app/user-guide](https://docs.photoprism.app/user-guide/) to learn how to sync, organize, and share your pictures. Our [User Guide](https://docs.photoprism.app/user-guide/) also covers many advanced topics, such as [migrating from Google Photos](https://docs.photoprism.app/user-guide/use-cases/google/) and [thumbnail quality settings](https://docs.photoprism.app/user-guide/settings/advanced/#preview-images).
A preliminary German version of the User Guide is published at [docs-de.photoprism.app](https://docs-de.photoprism.app/). We appreciate help with [improving the translation](https://github.com/photoprism/photoprism-docs-de) and keeping it up to date.
## Knowledge Base
Browse the [Knowledge Base](/kb/) for detailed information on specific product features, services, and related resources:
- [Compliance FAQ](/kb/compliance-faq/) for professional users and organizations
- [Getting Support](/kb/getting-support/) and [Reporting Bugs](/kb/reporting-bugs/)
- [Metadata Compatibility](/kb/metadata/)
- [Supported File Formats](/kb/file-formats/)
- [and more](/kb/)
## Developer Guide
Our [Developer Guide](https://docs.photoprism.app/developer-guide/) contains all the information you need to get started as a developer. It guides you from [setting up your development environment](https://docs.photoprism.app/developer-guide/setup/) and [creating pull requests](https://docs.photoprism.app/developer-guide/pull-requests/) to [running tests](https://docs.photoprism.app/developer-guide/tests/) and [adding translations](https://docs.photoprism.app/developer-guide/translations-weblate/). Multiple subsections provide details on specific features and links to external resources for further information.
> [!NOTE]
> **Want to learn more about our development practices?** Our approach relies heavily on agile methodologies with a high degree of automation and continuous integration. Many of the best practices we use and have proven to be effective are described in [Quality and Best Practices](https://docs.photoprism.app/developer-guide/code-quality/).
## GitHub Repository
The source code, including automated tests and a readme file that gives a [short and concise overview](https://github.com/photoprism/photoprism/blob/develop/README.md) of the project, can be found on GitHub at
## Config Options
You can use the following config options to specify the URL of an external CDN and change the cache expiration time for thumbnails and other static content:
| Environment | CLI Flag | Default | Description |
|------------------------------|---------------------|---------|-------------------------------------------------------------|
| PHOTOPRISM_CDN_URL | --cdn-url | | content delivery network `URL` |
| PHOTOPRISM_CDN_VIDEO | --cdn-video | false | stream videos over the specified CDN |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_CACHE_PUBLIC | --http-cache-public | true | allow static content to be cached by a CDN or caching proxy |
| PHOTOPRISM_HTTP_CACHE_MAXAGE | --http-cache-maxage | 2592000 | time in `SECONDS` until cached content expires |
| PHOTOPRISM_HTTP_VIDEO_MAXAGE | --http-video-maxage | 21600 | time in `SECONDS` until cached videos expire |
> [!NOTE]
> `PHOTOPRISM_HTTP_CACHE_PUBLIC` is enabled automatically as soon as a `PHOTOPRISM_CDN_URL` is
> configured, which is why it defaults to `true` here; without a CDN it defaults to `false`, as
> shown in the [config reference](/kb/config-options/#web-server). Publicly cacheable content can be
> served by a CDN or caching proxy without accessing your instance if it is already cached.
## CDN Providers
### bunny.net
If you don't have a CDN provider yet, we can recommend [bunny.net](https://link.photoprism.app/bunny-cdn). This EU-based company has a cute name, but is a reputable provider with [excellent performance](https://www.cdnperf.com/), a wide range of features, and more than 20,000 customers including big names like Hyundai. We also chose bunny.net for our website and public demo as they are fully compliant with the GDPR.[^1]
Pricing starts at $0.005/GB and there is no minimum usage or monthly fee, so you only pay for what you actually need.
[Learn more ›](https://link.photoprism.app/bunny-cdn)
### Cloudflare
[Cloudflare](https://www.cloudflare.com/) works similar to a [reverse proxy](https://docs.photoprism.app/getting-started/proxies/traefik/), allowing you to make a private server publicly accessible over the Internet. This means that users accessing your instance through their service will only see a single URL, as if they were connecting directly.
You must therefore not configure an external CDN URL, since this could prevent PhotoPrism from loading. Also note that their free version [does not include video streaming](https://www.cloudflare.com/plans/), so there may be problems with video playback if you are not a paying customer.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
[^1]: We receive a $20 credit when you sign up through our link, which helps us fund the project infrastructure.
---
# Using HTTPS
URL: https://www.photoprism.app/kb/https/
> In this guide, we show you how to enable transport encryption, add server certificates, and create new certificates.
## Why Use Encryption?
If you install PhotoPrism on a shared server so that it is not only accessible to the local host, always **secure the connection using HTTPS**. Your files and passwords will otherwise be transmitted in clear text and can be intercepted by anyone, including your provider, hackers, and governments. Backup tools and file synchronization apps may also refuse to connect.
> [!NOTE]
> HTTPS connections use Transport Layer Security (TLS) for encryption. TLS is a network protocol that establishes an encrypted connection to an authenticated peer over an untrusted network.
## How To Enable HTTPS
You have the following options to enable HTTPS/TLS when using our [latest stable release](https://docs.photoprism.app/release-notes/).
Note that after adding or updating certificates, it is required to restart PhotoPrism for the changes to take effect.
### 1. HTTPS Reverse Proxy
To run your instance behind an [HTTPS reverse proxy like Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/), we recommend that you explicitly disable TLS in PhotoPrism by setting `PHOTOPRISM_DISABLE_TLS` to `"true"` in your `compose.yaml` configuration:
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_DISABLE_TLS: "true"
```
> [!NOTE]
> Especially if your server also has other web applications installed and/or a proxy with working HTTPS is already in place, this may be the best option.
### 2. Self-Signed Certificate
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_DISABLE_TLS: "false"
PHOTOPRISM_DEFAULT_TLS: "true"
PHOTOPRISM_INIT: "https"
```
### 3. Custom Certificate
To use your own certificates, you can add a custom TLS certificate and private key to the `storage/config/certificates` folder with the filenames `www.example.com.crt` and `www.example.com.key`, replacing `www.example.com` with the actual server domain. For this, you can set the same config options as when using a self-signed certificate (see above).
Alternatively, you can specify a custom TLS certificate (`*.crt`) and private key (`*.key`) filename within the `storage/config/certificates` folder using the `PHOTOPRISM_TLS_CERT` and `PHOTOPRISM_TLS_KEY` [environment variables](https://docs.photoprism.app/getting-started/config-options/) in your `compose.yaml`, or use the corresponding [command flags](https://docs.photoprism.app/getting-started/config-options/):
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_TLS_CERT: "site.crt"
PHOTOPRISM_TLS_KEY: "site.key"
PHOTOPRISM_DISABLE_TLS: "false"
PHOTOPRISM_DEFAULT_TLS: "true"
PHOTOPRISM_INIT: "https"
```
> [!NOTE]
> We recommend that you keep the `PHOTOPRISM_DEFAULT_TLS` option enabled so that you can always connect securely over HTTPS even if there is a problem with your custom certificates.
## Obtaining Certificates
Valid server certificates can be obtained either from a commercial [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) (CA) like [ZeroSSL](#zerossl) or free of charge from [Let's Encrypt](#lets-encrypt):
### Let’s Encrypt
[Let's Encrypt](https://letsencrypt.org/) is an automatic certificate authority that provides you with free HTTPS/TLS certificates. Many web servers and reverse proxies such as [Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/) and [Caddy](https://docs.photoprism.app/getting-started/proxies/caddy-2/) have integrated support for obtaining single-domain certificates if your server is accessible on port 80 over the public Internet.
The creation of certificates for servers that are not publicly reachable or that are valid for all subdomains (wildcard) is alternatively possible with the [LEGO Let's Encrypt client](https://go-acme.github.io/lego/usage/cli/obtain-a-certificate/). If you use Docker and [DigitalOcean's free DNS service](https://m.do.co/c/f9725a28bb6b), the [command to run](https://go-acme.github.io/lego/usage/cli/obtain-a-certificate/) will look as follows (replace the certificate path, access token, domain names, and email address with the appropriate values):
```bash
docker run --rm -v "/path/to/certificates:/data/" \
-e DO_AUTH_TOKEN=Your_Access_Token goacme/lego -a \
-d "example.com" -d "*.example.com" --email="you@example.com" \
--dns=digitalocean --dns-timeout=180 --path=/data run
```
Note that this verification method only works if you use a [supported DNS provider](https://go-acme.github.io/lego/dns/) that LEGO can access through an API. Please refer to [its documentation](https://go-acme.github.io/lego/dns/) for details, as each provider requires different authentication credentials. If you are [using DigitalOcean](https://m.do.co/c/f9725a28bb6b), you can create the required access token in [your customer dashboard](https://cloud.digitalocean.com/account/api/tokens) and replace `Your_Access_Token` with it.
### ZeroSSL
[ZeroSSL](https://link.photoprism.app/zerossl) is a widely trusted commercial certificate authority with more than 500,000 customers worldwide. Its headquarters are located in [Vienna, Austria](https://link.photoprism.app/zerossl-contact).
Compared to Let's Encrypt, you can also create and revoke certificates through a user-friendly web interface, obtain certificates with a validity of more than 90 days, and choose between additional domain verification methods.[^1]
[Learn more ›](https://link.photoprism.app/zerossl)
## Troubleshooting
### Enabling Trace Log Mode
A good way to troubleshoot configuration issues is to increase the log level. To enable [trace log mode](https://docs.photoprism.app/getting-started/config-options/), set `PHOTOPRISM_LOG_LEVEL` to `"trace"` in the `environment:` section of the `photoprism` service (or use the `--trace` flag when running the `photoprism` command directly):
```yaml
services:
photoprism:
environment:
PHOTOPRISM_LOG_LEVEL: "trace"
...
```
Then [restart all services](https://docs.photoprism.app/getting-started/docker-compose/#step-2-start-the-server) for your changes to take effect:
```bash
docker compose stop
docker compose up -d
```
### Viewing Docker Service Logs
You can run this command to check the server logs for warnings and errors, including the last 100 messages (omit `--tail=100` to see them all, and `-f` to output only the last logs without watching them):
```bash
docker compose logs -f --tail=100
```
[Learn more ›](https://docs.photoprism.app/getting-started/troubleshooting/docker/#viewing-logs)
### Failed to Find Any PEM Data in Key Input
This error can indicate that your key file starts with an unexpected Byte Order Mark (BOM):
- https://www.google.com/search?q=failed+to+find+any+pem+data+tls+golang
- https://stackoverflow.com/questions/57596920/failed-to-find-any-pem-data-in-key
While BOMs are not strictly forbidden, there is only one way to encode UTF-8, and so they are not needed and extremely rare. As a result, a lot of software has problems with them.
You should be able to fix this by opening the file with a regular text or code editor (not Notepad) and then saving it again. Finally, restart all services for the changes to take effect:
```bash
docker compose stop
docker compose up -d
```
> [!NOTE]
> Our examples use the new `docker compose` command by default. If your server does not yet support it, you can still use `docker-compose` or alternatively `podman-compose` on Red Hat-compatible Linux distributions.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Setup Guide](https://docs.photoprism.app/getting-started/)
- [PhotoPrism® Knowledge Base](/kb/)
[^1]: We may receive a credit when you sign up through our link, which helps us fund the project infrastructure.
---
# Activating Your License
URL: https://www.photoprism.app/pro/kb/activation/
> This guide shows you how to create a customer account to get full access to our products and services.
## Step 1: Create a Customer Account ##
If you don't already have a customer account with us, you can register using the link you have received from us by email. Once this is done, or if you already have an account, [we will be happy](mailto:support@photoprism.app) to assign your licenses to that account.
> [!NOTE]
> Our [Privacy Policy](/privacy/) explains what information we collect and how we use it. Don't hesitate to [contact us](/contact/) if you have any questions about this policy, other privacy-related topics, or the registration process.
## Step 2: Install PhotoPrism Pro ##
Make sure you have the latest version of PhotoPrism® Pro installed. If you don't have it installed yet, our [Quickstart Guide](/pro/kb/quickstart/) will show you how to set it up and customize it to your needs in just a few steps.
> [!NOTE]
> In case you already have our free [Community Edition](https://docs.photoprism.app/getting-started/) or [PhotoPrism Plus](/plus/) installed, you can follow the [Upgrade Guide](/pro/kb/upgrade/) to get started with PhotoPrism® Pro.
## Step 3: Connect Your Account ##
To connect a new instance to your customer account, log in with the admin user[^1] that is automatically created during setup (see your configuration files or the app store documentation),[^2] and then follow these steps:
(1) In the main navigation click on *Upgrade*. If you do not see this link, you can manually navigate to */library/upgrade* in the browser toolbar.
(2) Click *Register* to sign in on our website and receive a code to connect your account.
(3) Finally, please restart your instance for the changes to take effect. You should now see the name of your company or organization in the footer of the *Settings* page instead of *Unregistered / Non-Production Use*. This means that your instance has been successfully activated for production use. Thank you very much!
### Troubleshooting ###
If you have installed the [latest release](/pro/kb/release-notes/), our [customer portal](https://my.photoprism.app/) shows that you have a Pro license assigned to your account, and you still get an error message when you follow the steps above:
(a) Try restarting your instance. We have found that this has solved the problem for many users.
(b) Should a restart not work, it is possible that your instance has problems connecting to the Internet. In this case, you will not be able to activate your instance, retrieve location data, or use the commercial maps: 
## Developer Guide
Our [Developer Guide](https://docs.photoprism.app/developer-guide/) contains all the information you need to get started as a developer. It guides you from [setting up your development environment](https://docs.photoprism.app/developer-guide/setup/) and [creating pull requests](https://docs.photoprism.app/developer-guide/pull-requests/) to [running tests](https://docs.photoprism.app/developer-guide/tests/) and [adding translations](https://docs.photoprism.app/developer-guide/translations-weblate/). Multiple subsections provide details on specific features and links to external resources for further information.
> [!NOTE]
> **Want to learn more about our development practices?** Our approach relies heavily on agile methodologies with a high degree of automation and continuous integration. Many of the best practices we use and have proven to be effective are described in [Quality and Best Practices](https://docs.photoprism.app/developer-guide/code-quality/).
## GitHub Repository
The source code, including automated tests and a readme file that gives a [short and concise overview](https://github.com/photoprism/photoprism/blob/develop/README.md) of the project, can be found on GitHub at 
## Outgoing Connections
As explained in our [Privacy Policy](/privacy/#section-7), reverse geocoding and interactive world maps depend on retrieving the necessary information [from us](/contact/) and [MapTiler AG](https://www.maptiler.com/contacts/), headquartered in Switzerland. Both services are provided with a very high level of privacy and confidentiality.
In order to successfully set up your installation and view location details in PhotoPrism® Pro, you must **allow requests to the following hosts** if you have a firewall installed, and make sure that your Internet connection is working:
- dl.photoprism.app
- my.photoprism.app
- cdn.photoprism.app
- charts.photoprism.app
- maps.photoprism.app
- setup.photoprism.app
- places.photoprism.app
- places.photoprism.xyz
In addition, the following API endpoints should be allowed so that public Docker images can be pulled from [Docker Hub](https://hub.docker.com/):
- auth.docker.io
- registry-1.docker.io
- index.docker.io
- dseasb33srnrn.cloudfront.net
- production.cloudfront.docker.com
- production.cloudflare.docker.com
## IPTables and Docker
On Linux, Docker manipulates the `iptables` rules to provide network isolation. This does have some implications for what you need to do if you want to have your own policies in addition to the rules Docker manages.
[Learn more ›](https://docs.docker.com/engine/network/packet-filtering-firewalls/)
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Getting Started with Rancher and Kubernetes
URL: https://www.photoprism.app/pro/kb/kubernetes/
> Practical tips and advice for running PhotoPrism® on a Kubernetes cluster.
## Table of Contents
[**Firewall Configuration**](#firewall-configuration)
- [Outgoing Connections](#outgoing-connections)
- [Required Ports and Interfaces](#required-ports-and-interfaces)
- [Firewall Rules Table](#firewall-rules-table)
- [NodePort Services](#nodeport-services)
- [Related Documentation](#related-documentation)
[**Linux Network Configuration**](#linux-network-configuration)
- [Name Server Configuration](#name-server-configuration)
- [Configuring a System-wide Proxy](#configuring-a-system-wide-proxy)
[**Linux Kernel Modules**](#linux-kernel-modules)
- [How to Enable `br_netfilter` on Ubuntu Linux](#linux-kernel-ubuntu)
- [How to Enable `br_netfilter` on Red Hat Enterprise Linux (RHEL)](#linux-kernel-redhat)
[**Rancher Cluster Setup**](#rancher-cluster-setup)
- [Registering a New Cluster Node](#registering-a-new-cluster-node)
- [Helm Chart for PhotoPrism® Pro](#helm-charts)
> [!NOTE]
> Although this guide uses IP addresses from the 10.0.0.0/24 subnet for internal networking in its configuration examples, you can also use other subnets and address ranges for the servers in your Kubernetes cluster.
### Firewall Configuration
#### Outgoing Connections
To successfully complete the setup and view location details in PhotoPrism®, please ensure that your firewall or HTTP/HTTPS proxy server allows outgoing connections to the following hosts:
- dl.photoprism.app
- my.photoprism.app
- cdn.photoprism.app
- charts.photoprism.app
- maps.photoprism.app
- setup.photoprism.app
- places.photoprism.app
- places.photoprism.xyz
In addition, access to the following hosts should be allowed for pulling the required images from [Docker Hub](https://hub.docker.com/):
- auth.docker.io
- registry-1.docker.io
- index.docker.io
- dseasb33srnrn.cloudfront.net
- production.cloudfront.docker.com
- production.cloudflare.docker.com
[Learn more ›](/pro/kb/firewall/)
#### Required Ports and Interfaces
**1. Internal Communication (10.0.0.0/24)**
Depending on your specific configuration, some or all of the following ports should be open to enable communication between the cluster nodes over the internal (private) network:
* **TCP 22**: Secure Shell (SSH)
* **TCP/UDP 53**: Domain Name System (DNS)
* **TCP/UDP 443**: HTTPS, [QUIC](https://en.wikipedia.org/wiki/QUIC)
* **TCP/UDP 2049**: NFS v4 (Network File System)
* **TCP 3306**: MariaDB Database Server
* **TCP/UDP 6443**: Kubernetes API
* **TCP/UDP 8472**: Flannel VXLAN (network overlay)
* **TCP 10250**: Kubelet API
* **TCP 2379-2380**: etcd (only for etcd nodes/control plane)
* **TCP 10251-10252**: kube-scheduler, kube-controller-manager (control plane only)
> **Note:** Since administrators or custom applications may require access to additional ports, it is recommended that no firewall rules are applied to restrict communication within the cluster.
**2. Public Interfaces**
Allow only the following ports for incoming traffic on public internet or intranet interfaces (as needed):
* **TCP 22**: SSH (for administration; restrict by IP as much as possible)
* **TCP 80**: HTTP Ingress (e.g. for redirects and certificate validation)
* **TCP/UDP 443**: HTTPS/QUIC Ingress (to access the application and admin interface)
* **TCP 6443**: Kubernetes API (for external access if required; restrict by IP if possible)
#### Firewall Rules Table
| Interface | Port(s) | Protocol | Source | Purpose |
|-------------------|-----------|----------------|----------------------------|------------------------------------------------------------------------|
| Internal (10.0.0) | allow all | ICMP, TCP, UDP | Admin, Kubernetes, MariaDB | Cluster operation |
| Public | | ICMP | Intranet, Internet | [Path MTU Discovery](https://en.wikipedia.org/wiki/Path_MTU_Discovery) |
| Public | 22 | TCP | Admin IPs, VPN | [Secure Shell (SSH)](https://en.wikipedia.org/wiki/Secure_Shell) |
| Public | 80 | TCP | Intranet, Internet | HTTP Ingress (optional) |
| Public | 443 | TCP, UDP | Intranet, Internet | HTTPS/[QUIC](https://en.wikipedia.org/wiki/QUIC) Ingress |
| Public | 6443 | TCP | Admin IPs, VPN | Kubernetes API |
> **Note:** Never expose the Flannel (8472), etcd (2379–2380) or Kubelet API (10250) ports on a public interface.
#### NodePort Services
The NodePort range (30000–32767, TCP/UDP) is the default port range that Kubernetes uses to publish NodePort services. This means that if services are exposed using the NodePort type (e.g. by Rancher), traffic can reach them via any node’s public or internal IP on a port in this range:
| Interface | Port(s) | Protocol | Source | Purpose |
|-------------------|-------------|----------|----------------|---------------------|
| Internal (10.0.0) | 30000-32767 | TCP/UDP | Cluster nodes | NodePort services |
| Public | 30000-32767 | TCP/UDP | As needed only | Public NodePort svc |
If Traefik is the only ingress controller used to expose applications (through ports 80 and 443 only), the NodePort range does not need to be opened externally. In this case, NodePort ports should only be accessible on the internal interface.
However, if workloads (or Rancher features such as the dashboard, monitoring or ingress controllers) are exposed via NodePort, you need to allow inbound traffic to these ports, but only on the interface(s) where the services should be accessible:
- *Typical*: Open the NodePort range on the internal interface (10.0.0.x) for inter-node communication.
- *Optional*: Open specific NodePort ports on the public interface to expose a service externally, without exposing the entire range to the world for security reasons.
#### Related Documentation
* [k3s Network Requirements](https://docs.k3s.io/networking)
* [Rancher - Ports Requirements](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-requirements/port-requirements)
* [Flannel Networking](https://github.com/flannel-io/flannel#flannel)
* [Traefik - Exposing Services](https://doc.traefik.io/traefik/expose/kubernetes/basic/)
* [Kubernetes - Publishing Services (ServiceTypes)](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types)
* [Kubernetes - Communication between Nodes and the Control Plane](https://kubernetes.io/docs/concepts/architecture/control-plane-node-communication/)
### Linux Network Configuration
#### Name Server Configuration
If your servers have a Linux distribution with `systemd` installed, it is recommended that you disable `systemd-resolved` before proceeding with the installation to avoid Rancher or Kubernetes name resolution problems:
```bash
sudo systemctl disable systemd-resolved --now
```
Make sure to also delete the symbolic link to the `systemd-resolved` configuration:
```bash
sudo rm /etc/resolv.conf
```
Once `systemd-resolved` is disabled, you can manually configure name resolution in `/etc/resolv.conf`, for example:
```
nameserver 8.8.8.8
nameserver 8.8.4.4
options edns0 trust-ad
search .
```
If the server is on a private network without a public IP address, you can set up a forwarding nameserver and configure it in `/etc/resolv.conf` as shown in this example (make sure to replace `10.0.0.2` with the actual nameserver IP address):
```
nameserver 10.0.0.2
```
#### Configuring a System-wide Proxy
To use this proxy service, you can add the following lines to `/etc/environment` (replace `10.0.0.2` with the actual proxy server address):
```
HTTP_PROXY="http://10.0.0.2:3128"
HTTPS_PROXY="http://10.0.0.2:3128"
FTP_PROXY="http://10.0.0.2:3128"
NO_PROXY="localhost,10.0.0.0/8,127.0.0.0/8,172.16.0.0/12,192.168.0.0/16,::1"
```
On Debian/Ubuntu, create or edit `/etc/apt/apt.conf.d/95proxies` to include the following:
```
Acquire::http::Proxy "http://10.0.0.2:3128";
Acquire::https::Proxy "http://10.0.0.2:3128";
```
The proxy settings for Snap on Ubuntu Linux can be changed with the following commands:
```bash
sudo snap set system proxy.http="http://10.0.0.2:3128"
sudo snap set system proxy.https="http://10.0.0.2:3128"
```
### Linux Kernel Modules
The `br_netfilter` Linux kernel module is crucial for Kubernetes networking—especially when using network plugins (like Flannel, Calico, Cilium, etc.) that rely on bridged networking.
Without the module, packets traveling across Linux bridges bypass `iptables` by default, so firewall rules, NAT, or port forwarding won’t apply to inter-pod or pod-to-service traffic.
You must therefore ensure that the `br_netfilter` module is loaded before installing Rancher or Kubernetes cluster nodes:
#### How to Enable `br_netfilter` on Ubuntu Linux
```bash
echo "br_netfilter" | sudo tee /etc/modules-load.d/br_netfilter.conf
sudo modprobe br_netfilter
sudo sed -i 's/#net.ipv4.ip_forward=1/net.ipv4.ip_forward=1/g' /etc/sysctl.conf
```
Running the command `sudo lsmod` will show a list of all the currently loaded kernel modules. It should now include `br_netfilter`.
Also ensure that your servers have the latest security updates installed:
```bash
sudo apt update
sudo apt dist-upgrade
```
Then, restart your servers before proceeding with the installation.
#### How to Enable `br_netfilter` on Red Hat Enterprise Linux (RHEL)
```bash
echo "br_netfilter" | sudo tee /etc/modules-load.d/br_netfilter.conf
sudo modprobe br_netfilter
```
Running the command `sudo lsmod` will show a list of all the currently loaded kernel modules. It should now include `br_netfilter`.
You should also ensure that the latest security updates are installed. Then, restart your servers before proceeding with the installation.
### Rancher Cluster Setup
#### Registering a New Cluster Node
To add a new node to a Rancher-managed cluster, run the following command on the server you want to add (replace the Rancher server hostname and authentication token, as well as the node's external and internal IP addresses):
```bash
curl -fL https://[server_hostname]/system-agent-install.sh | sudo sh -s - \
--server https://[server_hostname] --label 'cattle.io/os=linux' \
--token [token] \
--address [external_ip] --internal-address [internal_ip] \
--etcd --controlplane --worker
```
After running the script, you can use the following command to view the logs and check whether the node is connecting to the server:
```bash
sudo tail -f /var/log/syslog
```
If the service fails to start due to an incorrect `token`, wrong server hostname, or other configuration problem, you can try resolving these issues and then restarting the service with the following command:
```bash
sudo systemctl restart rancher-system-agent
```
The following script removes the Rancher agent from the server, so you can start from scratch or use the server for other purposes:
```bash
sudo rancher-system-agent-uninstall.sh
```
> **Note:** Be sure to remove the node from the cluster in the Rancher web interface before uninstalling the agent, shutting down the server permanently, or reinstalling its operating system.
#### Helm Chart for PhotoPrism® Pro
Our `photoprism-pro` chart, hosted at [**charts.photoprism.app/photoprism**](https://charts.photoprism.app/photoprism), is compatible with Rancher and includes safe defaults for standalone installations. It can optionally be integrated with a [PhotoPrism® Portal](/pro/kb/portal/) server for automated provisioning, shared single sign-on, and centralized [access control](/pro/kb/openid-connect/#cluster-authentication) across multiple instances.
[Learn more ›](/pro/kb/helm-chart/)
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® Portal Knowledge Base](/portal/kb/)
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Getting Updates
URL: https://www.photoprism.app/pro/kb/updates/
> This guide shows you how to get and install updated versions of PhotoPrism® Pro.
### Docker Compose
Open a terminal and change to the folder where your `compose.yaml` or `docker-compose.yml` file is located.[^1] Now run the following commands to download the [most recent version](/pro/kb/release-notes/) from our private registry and restart your instance in the background:[^2]
```
docker compose up -d --pull always
```
Pulling a new version can take several minutes, depending on your internet connection speed. Advanced users can [add this to a `Makefile`](https://dl.photoprism.app/docker/Makefile) so that they only have to type a single command like `make update`.
> [!NOTE]
> Even when you use an image with the `:latest` tag, Docker does not automatically download new images for you. You can either manually upgrade as shown above, or set up a service like [Watchtower](#watchtower) to get automatic updates.
#### Config Examples
We recommend that you compare your own `compose.yaml` with [our latest examples](/pro/kb/quickstart/#step-1) from time to time, as they may include new [config options](/pro/kb/config-options/) or other enhancements relevant to you.
#### Development Preview
You can test upcoming features and enhancements by changing the image from `photoprism/pro:latest` to `photoprism/pro:preview` in your [`compose.yaml`](https://dl.photoprism.app/docker/). Then pull the most recent image and restart your instance as shown above.
#### Watchtower
Adding [Watchtower](https://github.com/nicholas-fedor/watchtower) as a service to your `compose.yaml` will automatically keep images up-to-date:
```yaml
services:
watchtower:
image: nickfedor/watchtower
restart: unless-stopped
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
```
> [!NOTE]
> Automatic updates may interrupt indexing and import operations. Only enable Watchtower if you are comfortable with this.
### Pure Docker
Open a terminal on your server, and run the following command to pull the most recent container image:[^2]
```
docker pull photoprism/pro:latest
```
### Complete Rescan
We recommend performing a [complete rescan](https://docs.photoprism.app/user-guide/library/originals/#when-should-complete-rescan-be-selected) after major updates to take advantage of new search filters and sorting options. Be sure to [read the notes for each release](/pro/kb/release-notes/) to see what changes have been made and if they might affect your library, for example, because of the file types you have or because new search features have been added. If you encounter problems that you cannot solve otherwise (i.e. before reporting a bug), please also try a rescan and see if it solves the problem.
You can start a [rescan from the user interface](https://docs.photoprism.app/user-guide/library/originals/) by navigating to *Library* > *Index*, selecting "Complete Rescan", and then clicking "Start". Manually entered information such as labels, people, titles or descriptions will not be modified when indexing, even if you perform a "complete rescan".
> [!NOTE]
> Be careful not to start multiple indexing processes at the same time, as this will lead to a high server load.
### MariaDB Server
Our [configuration examples](/pro/kb/quickstart/#step-1) are generally based on the [current stable version](https://mariadb.com/kb/en/mariadb-server-release-dates/) to take advantage of performance improvements. This does not mean that [older versions](https://docs.photoprism.app/getting-started/#databases) are no longer supported and you must upgrade immediately. We recommend not using the `:latest` tag for the MariaDB Docker image and to upgrade manually by changing the tag once we had a chance to test a new major version, e.g.:
```yaml
services:
mariadb:
image: mariadb:12.3
...
```
If MariaDB fails to start after upgrading from an earlier version (or migrating from MySQL), the internal management schema may be outdated. See [Troubleshooting MariaDB Problems](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#version-upgrade) for instructions on how to fix this.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
[^1]: The default [Docker Compose](https://docs.docker.com/compose/) config filename is `compose.yaml`. For simplicity, it doesn't need to be specified when running `docker compose` in the same directory. Config files for other apps or instances should be placed in separate folders.
[^2]: Our guides use the new `docker compose` command by default. If your server does not yet support it, the old `docker-compose` command will still work. Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the `docker` and `docker compose` commands with `podman` and `podman-compose` as drop-in replacements.
---
# Helm Chart
URL: https://www.photoprism.app/pro/kb/helm-chart/
> Deploys PhotoPrism® Pro on Kubernetes
Our `photoprism-pro` chart, hosted at [**charts.photoprism.app/photoprism**](https://charts.photoprism.app/photoprism), is compatible [with Rancher](/pro/kb/kubernetes/) and includes safe defaults for standalone installations. It can optionally be integrated with a PhotoPrism® Portal server for automated provisioning.
## Features
- Runs the `photoprism/pro` image with non-root defaults (UID/GID 1000) and baseline security settings.
- Creates persistent volumes for originals (optional) and application storage with conservative 10 GiB / 5 GiB defaults that can be resized post-install.
- Supports either SQLite (default) or MariaDB/MySQL by overriding the database block.
- Optional LDAP and OIDC configuration mapped directly to PhotoPrism environment variables.
- Portal integration is opt-in; when enabled, the chart can consume the standard `photoprism-cluster-secrets` or user-defined secrets without hard-coding customer data.
## Quick Start
```bash
helm repo add photoprism https://charts.photoprism.app/photoprism
helm repo update photoprism
helm upgrade --install photos photoprism/photoprism-pro \
--namespace photos --create-namespace
```
This deploys PhotoPrism with SQLite storage. To use MariaDB (recommended for production), supply the connection details:
```bash
helm upgrade --install photos photoprism/photoprism-pro \
--namespace photos \
--set database.driver=mysql \
--set database.server=mariadb.default.svc.cluster.local:3306 \
--set database.name=photoprism \
--set database.user=photoprism \
--set database.password=changeme
```
## Persistence
- `persistence.storage` provides the writable application directory (`/photoprism/storage`).
- `persistence.originals` defaults to a PVC but can be replaced with NFS by enabling `persistence.originals.nfs`.
- The chart never assumes Longhorn; it honours your cluster default storage class unless overridden via `persistence.storageClassName`.
## Optional Portal Integration
Set `cluster.integration.enabled=true` to populate cluster-specific environment variables:
```yaml
cluster:
integration:
enabled: true
secretName: photoprism-cluster-secrets # optional, defaults to this name
```
If the secret is not available, you may provide the values inline (`domain`, `portalURL`, `joinToken`, …). All secret references are marked optional so the chart remains usable without a Portal deployment.
## Values Reference
Run `helm show values photoprism/photoprism-pro` for a complete list of configurable options. Common adjustments include:
- `config.PHOTOPRISM_SITE_TITLE` / `config.PHOTOPRISM_SITE_DESCRIPTION`
- `config.PHOTOPRISM_PASSWORD_LENGTH`, `config.PHOTOPRISM_SESSION_*`
- `ldap.*` and `oidc.*` blocks for enterprise authentication
- `persistence.*` for storage sizing or NFS mounting
## Networking and TLS
The chart exposes PhotoPrism on TCP 2342 through a ClusterIP service. You can override the service type or enable an Ingress resource when you terminate TLS in the cluster edge:
```yaml
service:
type: ClusterIP
port: 2342
ingress:
enabled: true
className: traefik
hosts:
- host: photos.example.com
paths:
- path: /
pathType: Prefix
tls:
- hosts:
- photos.example.com
secretName: photos-tls
```
Because TLS typically terminates at the ingress or proxy layer, the chart keeps `PHOTOPRISM_DISABLE_TLS` set to `true`. Only enable PhotoPrism’s internal TLS if your cluster design requires end-to-end encryption and you manage the certificates yourself.
## Security Notes
- Admin passwords are generated on first install when `adminPassword` is empty and stored in the release secret (`
### CLI Commands
As an alternative to the [web user interface](#admin-web-ui), you can [run the following commands in a terminal](/pro/kb/cli/) to perform tasks such as adding, viewing, editing and deleting user accounts:
| Command | Description |
|---------------------------------------------|----------------------------------------------|
| `photoprism users ls [search]` | Searches existing user accounts |
| `photoprism users legacy [search]` | Searches legacy user accounts |
| `photoprism users add [options] [username]` | Adds a new user account |
| `photoprism users show [username]` | Displays user account information |
| `photoprism users mod [options] [username]` | Modifies an existing user account |
| `photoprism users rm [username]` | Removes a user account |
| `photoprism users reset` | Removes all accounts and resets the database |
| `photoprism passwd [username]` | Changes the password required to log in |
| `photoprism passwd --rm [username]` | Removes the password from a local account |
#### Account Options
The `users add` and `users mod` commands support these flags to set or change account properties:
| Command Flag | Description |
|--------------------------------------|---------------------------------------------------------------------------------|
| `--name NAME`, `-n NAME` | full NAME for display in the interface |
| `--email EMAIL`, `-m EMAIL` | unique EMAIL address of the user |
| `--password PASSWORD`, `-p PASSWORD` | PASSWORD for authentication |
| `--role value`, `-r value` | user account ROLE (admin, user, viewer, contributor or guest) (default: "user") |
| `--auth PROVIDER`, `-A PROVIDER` | authentication PROVIDER (default, local, oidc, ldap or none) |
| `--auth-id ID` | authentication ID e.g. Subject ID or Distinguished Name (DN) |
| `--attr ATTRIBUTES`, `-a ATTRIBUTES` | custom user account ATTRIBUTES |
| `--superadmin`, `-s` | make user super admin with full access |
| `--no-login`, `-l` | disable login on the web interface |
| `--webdav`, `-w` | allow to sync files via WebDAV |
| `--base-path value, `-d value` | restrict search to this originals folder |
| `--upload-path value`, `-u value` | upload files to this sub-folder |
| `--disable-2fa` | deactivate two-factor authentication |
#### Changing a Password
Running the following in a terminal changes the password of an existing user without affecting other account settings, e.g. if you cannot remember the currently set password or if there was a problem [configuring the initial admin account](https://www.photoprism.app/pro/kb/config-options/) (replace `[username]` with the username of the account you want to update):
```bash
photoprism passwd [username]
```
Note that when you use Docker Compose and do not [already have a terminal session open](https://docs.photoprism.app/getting-started/docker-compose/#opening-a-terminal), you must prepend `docker compose exec photoprism` so that the command is executed within the `photoprism` container, for example:
```bash
docker compose exec photoprism photoprism passwd admin
```
> [!NOTE]
> The examples in our documentation use the new `docker compose` command by default. If your server does not yet support it, you can still use `docker-compose` or alternatively `podman-compose` on Red Hat-compatible Linux distributions.
## Removing a Password
Changing the authentication of an existing account to a password-less provider like [*OIDC*](https://docs.photoprism.app/getting-started/advanced/openid-connect/#existing-accounts) will not remove a previously set password, so it can still be used to log in (optionally also with [2FA](https://docs.photoprism.app/user-guide/users/2fa/)).
If a local password has been set for [such an account](https://docs.photoprism.app/getting-started/advanced/openid-connect/#existing-accounts) that should no longer be used, you can remove it by running the following command [in a terminal](https://docs.photoprism.app/getting-started/docker-compose/#opening-a-terminal):
```bash
photoprism passwd --rm [username]
```
#### Creating a New Account
The command `photoprism users add` creates a new user account. For example, you could run the following to add a new admin with the username "bob" and the password "mysecret":
```bash
docker compose exec photoprism photoprism users add -p mysecret -n "Bob" bob
```
> [!NOTE]
> If you do not specify an initial password with the `-p` flag, you will be prompted to enter a password for the new account. Further account properties can be set with the flags listed above.
#### Viewing Account Details
To view the account properties of a specific user, use the `show` subcommand:
```
docker compose exec photoprism photoprism users show bob
```
#### Searching User Accounts
To list all existing accounts, you can run the following:
```
docker compose exec photoprism photoprism users ls
```
With the `photoprism users ls` command, you can also find specific accounts based on a search term you provide:
```
docker compose exec photoprism photoprism users ls bob
```
To display a description and the available options for a command, use the `--help` flag:
```
docker compose exec photoprism photoprism users ls --help
```
### Session Management
You can use the following terminal commands to create, inspect and, if necessary, delete access tokens for the authentication of browsers and other clients (including [app passwords](https://docs.photoprism.app/user-guide/settings/account/#apps-and-devices)):
| CLI Command | Description |
|-------------------------------------|----------------------------------------------------------|
| `photoprism auth ls [search]` | Lists currently authenticated users and clients |
| `photoprism auth add [username]` | Adds a new authentication secret for client applications |
| `photoprism auth show [identifier]` | Shows detailed information about a session |
| `photoprism auth rm [identifier]` | Deletes a session by id or access token |
| `photoprism auth reset --yes` | Resets the authentication of all users and clients |
In addition, login attempts can be viewed in the application service logs as well as with this command:
```
docker compose exec photoprism photoprism audit logins [search]
```
[Learn more ›](/pro/kb/monitoring/)
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Metadata Compatibility
URL: https://www.photoprism.app/pro/kb/metadata/
> Get an overview of the supported Exif, XMP, IPTC, and DCMI tags and their internal field names in PhotoPrism® Pro.
| Field | Type | Exiftool | Adobe XMP | DCMI |
|:--------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------|:-----------------|
| Altitude | decimal | GlobalAltitude, GPSAltitude | | |
| Aperture | decimal | ApertureValue, Aperture | | |
| FNumber | decimal | FNumber | | |
| FPS | decimal | VideoFrameRate, VideoAvgFrameRate | | |
| FocalDistance | decimal | HyperfocalDistance | | |
| Duration | duration | Duration, MediaDuration, TrackDuration, PreviewDuration | | |
| Favorite | flag | Favorite | | |
| Flash | flag | FlashFired | | |
| Keywords | list | Keywords | | |
| FocalLength | number | FocalLength, FocalLengthIn35mmFormat | | |
| Frames | number | FrameCount, AnimationFrames | | |
| Height | number | ImageHeight, ImageLength, PixelYDimension, ExifImageHeight, SourceImageHeight | | |
| ImageType | number | HDRImageType | | |
| Iso | number | ISO | | |
| Pages | number | PageCount, NPages, Pages | | |
| Rotation | number | Rotation | | |
| Width | number | ImageWidth, PixelXDimension, ExifImageWidth, SourceImageWidth | | |
| Artist | text | Artist, Creator, By-line, OwnerName, Owner | Creator | |
| CameraMake | text | CameraMake, Make | Make | |
| CameraModel | text | CameraModel, Model, CameraID, UniqueCameraModel | CameraModel, Model | |
| CameraOwner | text | OwnerName | | |
| CameraSerial | text | SerialNumber | | |
| Caption | text | Description, ImageDescription, Caption, Caption-Abstract | Description, Description.Alt | |
| Codec | text | CompressorID, VideoCodecID, CodecID, OtherFormat, VideoCodec, FileType | | |
| ColorProfile | text | ICCProfileName, ProfileDescription | | |
| Copyright | text | Rights, Copyright, CopyrightNotice, WebStatement | Rights, Rights.Alt | |
| DocumentID | text | ContentIdentifier, MediaGroupUUID, BurstUUID, OriginalDocumentID, DocumentID, ImageUniqueID, DigitalImageGUID | | |
| Exposure | text | ExposureTime, ShutterSpeedValue, ShutterSpeed, TargetExposureTime | | |
| FileName | text | FileName | | |
| GPSLatitude | text | GPSLatitude | | |
| GPSLongitude | text | GPSLongitude | | |
| GPSPosition | text | GPSPosition | | |
| InstanceID | text | InstanceID, DocumentID | | |
| LensMake | text | LensMake | | |
| LensModel | text | LensModel, Lens, LensID | LensModel, Lens | |
| License | text | UsageTerms, License | | |
| Notes | text | Comment, UserComment | | |
| Projection | text | ProjectionType | | |
| Software | text | Software, Producer, CreatorTool, CreatorSubTool, HistorySoftwareAgent, ProcessingSoftware | | |
| Subject | text | Subject, PersonInImage, ObjectName, HierarchicalSubject, CatalogSets | Subject | |
| TimeOffset | text | OffsetTime, OffsetTimeOriginal, OffsetTimeDigitized | | |
| Title | text | Title, Headline | dc:title | title, title.Alt |
| CreatedAt | timestamp | SubSecCreateDate, CreationTime, CreationDate, CreateDate, MediaCreateDate, ContentCreateDate, TrackCreateDate | | |
| TakenAt | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationTime, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | DateCreated, CreationTime | |
| TakenAtLocal | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | | |
| TakenGps | timestamp | GPSDateTime, GPSDateStamp | | |
## Metadata Tags by Namespace ##
| Namespace | Documentation |
|:--------------------|:---------------------------------------------------------------------|
| Exiftool | https://exiftool.sourceforge.net/TagNames/EXIF.html |
| Exiftool XMP | https://exiftool.sourceforge.net/TagNames/XMP.html |
| Adobe XMP | https://docs.photoprism.app/developer-guide/metadata/xmp/#references |
| Dublin Core (DCMI) | https://www.dublincore.org/specifications/dublin-core/dcmi-terms/ |
| IPTC Photo Metadata | https://iptc.org/standards/photo-metadata/iptc-standard/ |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# PhotoPrism® Portal & Clusters
URL: https://www.photoprism.app/pro/kb/portal/
> Centrally manage authentication, branding, and multiple instances from a single management server.
The PhotoPrism® Portal is a central management server for running several PhotoPrism® instances as a *cluster*. Instead of configuring and maintaining each instance on its own, the Portal provides shared single sign-on, centralized access control, consistent branding, and a single place to register and manage instances.
> [!NOTE]
> Running a Portal-managed cluster is only available with our [team plans](/teams/#compare), not the [personal editions](/editions/#compare).
For step-by-step deployment guides — Quickstart, configuration options, Kubernetes, OpenShift, and MariaDB Enterprise — see the [PhotoPrism® Portal Knowledge Base](/portal/kb/).
## What the Portal Does
A Portal combines several roles that would otherwise have to be set up separately for every instance:
- **Identity provider** — users sign in once at the Portal, which then logs them in to the instances they are allowed to use. See [Cluster Authentication & Access Control](/pro/kb/openid-connect/#cluster-authentication).
- **Node registry** — keeps track of every registered instance, its address, role, and database, and issues the credentials each instance uses to talk to the Portal.
- **Theme distributor** — stores a single branding theme that instances download and keep in sync automatically.
- **Optional reverse proxy** — can serve several instances under one shared domain using `/i/
When using the *Web editor*, please make sure that related values remain on the [same indentation level](https://docs.photoprism.app/developer-guide/technologies/yaml/) and that lists start with a dash as shown in our template.
### Volumes ###
You need to explicitly [specify the directories](https://docs.docker.com/reference/compose-file/services/#volumes) you want to use on your NAS device, since PhotoPrism can't see files in folders that have not been shared. This is an important security feature and allows for a flexible configuration without having to change any other variables.
> **It is important that all folders specified in the "volumes" sections are located on a persistent volume on your device.** We recommend changing the relative paths used in our example to absolute paths in order to avoid potential data loss, e.g. if the default application folder managed by Portainer changes or is reset after an update.
>
> The volume mount paths to configure depend on your NAS device and its settings. As on most operating systems, a dot followed by a slash `./` can be used to specify a path relative to the current directory. If you keep the defaults, all files will be located in the internal application folder that Portainer automatically creates when you add a new stack.
#### Database ####
Our [stack template](https://setup.photoprism.app/pro/portainer/stack.yml) includes a pre-configured [MariaDB](https://mariadb.com/) database server that stores its data in the internal application folder by default:
```yaml
services:
mariadb:
volumes:
- "./database:/var/lib/mysql"
```
If your NAS device has a mixed drive configuration with solid-state drives (SSDs) and traditional hard disks, we recommend that you change `./database` to an absolute path located on an SSD as this [significantly improves performance](https://docs.photoprism.app/getting-started/troubleshooting/performance/#storage), for example:
```yaml
- "/mnt/ssd/database:/var/lib/mysql"
```
> [!NOTE]
> Database files should [never be located on an unreliable device](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#corrupted-files) such as a USB flash drive, SD card, or network folder.
#### /photoprism/originals ####
The *originals* folder contains your original photo and video files:
```yaml
services:
photoprism:
volumes:
- "./originals:/photoprism/originals"
```
We recommend that you change `./originals` to the directory on your NAS where your existing media files are, for example:
```yaml
- "/mnt/photos:/photoprism/originals"
```
Additional directories can be mounted as sub folders of `/photoprism/originals` (depending on [overlay filesystem support](https://docs.photoprism.app/getting-started/troubleshooting/docker/#overlay-volumes)):
```yaml
volumes:
- "/mnt/photos:/photoprism/originals"
- "/mnt/videos:/photoprism/originals/videos"
```
> [!NOTE]
> If you want to start with an empty library, you can mount any directory that has enough free space for your needs.
#### /photoprism/storage ####
The *storage* folder is used to save config, cache, thumbnail, and sidecar files. It must always be specified so that you do not lose these files after a restart or upgrade.
If available, we recommend that you put the *storage* folder on a [local SSD drive](https://docs.photoprism.app/getting-started/troubleshooting/performance/#storage) for best performance. You can otherwise keep the default to store the files in the internal application folder:
```yaml
services:
photoprism:
volumes:
- "./storage:/photoprism/storage"
```
> [!NOTE]
> Never configure the *storage* folder to be inside the *originals* folder unless the name starts with a `.` to indicate that it is hidden.
Should you later want to move your instance to another NAS, the easiest and most time-saving way is to copy the entire *storage* folder along with your *originals* and *database*.
#### /photoprism/import ####
You can optionally mount an *import* folder from which files can be transferred to the *originals* folder in a structured way that avoids duplicates, for example:
```yaml
services:
photoprism:
volumes:
- "/mnt/media/usb:/photoprism/import"
```
[Imported files](https://docs.photoprism.app/user-guide/library/import/) receive a canonical filename and will be organized by year and month. You should never configure the *import* folder to be inside the *originals* folder, as this will cause a loop by importing already indexed files.
> [!NOTE]
> Even if you don't specify an *import* folder, adding files via [Web Upload](https://docs.photoprism.app/user-guide/library/upload/) and [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/) remains possible unless [read-only mode](/pro/kb/config-options/) is enabled or the [features have been disabled](https://docs.photoprism.app/user-guide/settings/general/).
## Step 2: Finalize Setup ##
To complete the setup, [download the *stack.env* file from our server](https://setup.photoprism.app/pro/portainer/stack.env) (right click and *Save Link As...*), click "Load variables from .env file", upload it to Portainer, and then [change the values according to your needs](/pro/kb/config-options/):
> Always change `PHOTOPRISM_ADMIN_PASSWORD` so that the app **starts with a secure initial password**.
Never use easy-to-guess passwords or default values like `insecure` on publicly accessible instances.
There is no default in case no password was provided. A minimum length of 8 characters is required.
> [!NOTE]
> It is **not possible to change the database password** with `MARIADB_PASSWORD` after MariaDB has been started for the first time. However, choosing a secure password is not essential if you don't [expose the database to other apps or hosts](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#cannot-connect). To enable [automatic schema updates](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#auto-upgrade) after upgrading to a new major version, make sure that `MARIADB_AUTO_UPGRADE` is set to a non-empty value.
When you are done, scroll down and click "Deploy the stack" without changing any of the other options:
After waiting a few moments, you should be able to log in as `admin` with the password specified in `PHOTOPRISM_ADMIN_PASSWORD` when you navigate to **
Now click the :fontawesome-solid-terminal: button belonging to the *photoprism-photoprism-1* container and [accept the default settings](https://dl.photoprism.app/img/screenshots/portainer/console-settings.png) to open a terminal:
Running `photoprism help` lists all commands and [options](/pro/kb/config-options/) available in the current version:
```bash
photoprism help
```
Use the `--help` flag to see a detailed command description, for example:
```bash
photoprism backup --help
```
The command-line interface is also well suited for job automation using a [scheduler](https://dl.photoprism.app/docker/scheduler/).
### Examples
| Action | Command |
|-------------------------------------------------------------------------------|-------------------------------------|
| *Display Config Values* | `photoprism show config` |
| *Show Migration Status* | `photoprism migrations ls` |
| *Repeat Failed Migrations* | `photoprism migrations run -f` |
| *Reset Database* | `photoprism reset --yes` |
| *Backup Database* | `photoprism backup -a -i` |
| *Restore Database* | `photoprism restore -a -i` |
| *Change Password* | `photoprism passwd [username]` |
| *Remove Password* | `photoprism passwd --rm [username]` |
| *Show User Management Commands* | `photoprism users help` |
| *Reset User Accounts* | `photoprism users reset --yes` |
| *Reset Sessions and Access Tokens* | `photoprism auth reset --yes` |
| *Show Face Recognition Commands* | `photoprism faces help` |
| *Index Faces* | `photoprism faces index` |
| *Reset People & Faces* | `photoprism faces reset -f` |
| *Transcode Videos to AVC* | `photoprism convert` |
| *Regenerate Thumbnails* | `photoprism thumbs -f` |
| [*Update Index*](https://docs.photoprism.app/user-guide/library/originals/) | `photoprism index --cleanup` |
| [*Move to Originals*](https://docs.photoprism.app/user-guide/library/import/) | `photoprism import [path]` |
| [*Copy to Originals*](https://docs.photoprism.app/user-guide/library/import/) | `photoprism cp [path]` |
## PhotoPrism® Documentation ##
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Product FAQ
URL: https://www.photoprism.app/pro/kb/product-faq/
> Get answers to the most frequently asked questions about product features.
### How many organisations are using your product?
PhotoPrism has more than 35,000 active installations, growing daily. Because we [respect the privacy](/privacy/) of our users, we do not have detailed information about whether these are run by individuals, businesses, or other organizations. PhotoPrism® Pro, our version for professional users, is currently used by a number of news agencies, NGOs as well as governments.
### Is your system SSO enabled?
PhotoPrism® Pro supports single sign-on via [OpenID Connect (OIDC)](https://www.photoprism.app/pro/kb/openid-connect/) and lets you authenticate users against a central [Lightweight Directory Access Protocol (LDAP) or Active Directory (AD)](https://www.photoprism.app/pro/kb/ldap/) server, so that users on the corporate network can sign in with their existing usernames and passwords.
### Is your application a SaaS solution?
Most customers prefer to host PhotoPrism® Pro on-premises for maximum data protection and performance. However, we can also provide a fully managed cloud service and other professional services for an additional fee upon request. Installation instructions and system requirements can be found in our [Knowledge Base](/pro/kb/).
Unlike many competing solutions, PhotoPrism® Pro has no library size limit, so licensing costs do not depend on how many files you have. In order to provide a quote for a fully managed cloud solution, please let us know your availability requirements and which hosting location you prefer.
### Which photo and video file formats are supported?
Our [Knowledge Base](/pro/kb/) provides you with an overview of [all supported formats](/pro/kb/file-formats/), which includes the most common image, video and vector graphics file types.
### What is the maximum number of files that are allowed or can be managed?
There is no explicit limit to the number of files, except for the limitations imposed by the underlying database, the server's file system, and the size of the variables used as record identifiers, i.e. in the billions.
The number of files is primarily limited by the storage available. Practical usability also relies on the server's CPU and memory, while the time needed for indexing depends on the size of your files and their formats. We recommend that you test the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license.
### Is it possible to bulk upload photos and videos?
To sync or bulk upload photos and videos, you can use any application or operating system that supports [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/), such as Microsoft's Windows Explorer and Apple's Finder. This allows you to connect directly to PhotoPrism and open, edit, and delete files on your computer as if they were local.
### Can external vendors be granted to upload photos and videos?
Users with the [Contributor](https://www.photoprism.app/pro/kb/roles/) role have read-only access (view and download) to the resources that are in their configured base path, and to the albums that an admin or regular user has shared with them through a link. The Contributor role does not have access to the entire library, but does have the right to upload files to the directory specified as the upload path.
### Is it possible to identify people and exclude them from a photo selection?
PhotoPrism includes [face recognition](https://docs.photoprism.app/user-guide/organize/people/) functionality that lets you find pictures of specific people. New faces are detected as you scan your library. They are then grouped by similarity so you can quickly match them. By setting the [private flag](https://docs.photoprism.app/user-guide/organize/private/), you can hide certain photos or videos from shared albums and unprivileged users. In an upcoming release, you'll also be able to flag a person directly, so images can be hidden in the same way.
### In what ways can photos and videos be searched?
PhotoPrism offers a wide range of [search filters](https://www.photoprism.app/pro/kb/search-filters/) that let you find specific photos and videos, for example, by person, location, and tags.
### Can you jump to a specific point in a video where a person is tagged?
No, this is not possible at the moment. If we see a demand for such a feature, we will consider adding it to our roadmap.
### Can you search video transcripts to find a particular video?
PhotoPrism supports text search for most photo and video metadata. However, it does not automatically create video transcripts.
### Can you tag people in videos?
At the moment, only a single still image is extracted from the videos. If a face is detected there, it can be tagged. Manual tagging is planned for an upcoming release. If we see a demand for detecting faces throughout the length of a video, we will consider adding this to our roadmap.
### Is it possible to add tags or other picture metadata?
Yes, you can add metadata to your photos/videos when you open the picture details in the [edit dialog](https://docs.photoprism.app/user-guide/organize/edit/).
### Is there a bulk edit feature to change the metadata of multiple pictures at once?
Not yet, but this is planned for an [upcoming release](https://github.com/photoprism/photoprism/issues/271).
### Is it possible to share a link so someone can view a photo gallery?
Yes, it is possible to share albums using secret links. You can create multiple links for each album and optionally set an expiration date. No additional apps need to be installed and no registration is required for this to work.
### What is the largest file size you support when uploading?
There is no specific limit. It depends only on the server configuration.
### What collaboration features are integrated in your product?
PhotoPrism includes advanced multi-user features with a set of account roles. These roles are intended for applications where multiple users share a single library, for example, to give employees access to the library without granting write permissions or exposing sensitive content.
It is recommended to set up multiple instances if you have multiple teams, where each team wants to manage their own files independently and share only selected albums. This way you can avoid problems with conflicting library settings, file permissions, and dealing with duplicates.
### Can tags be automatically assigned based on the attributes of a folder?
PhotoPrism searches all metadata, including file and folder names, and extracts tags from it where possible. Since the source code is available, you can also customize this if needed.
### Can your software integrate with our employee directory to automatically tag specific people?
This is not a standard functionality. However, since the source code is available, you can customize it to your needs.
### Do you have a concept of cold and hot storage?
You can move photos and videos that you don't want to keep in your collection to the [Archive](https://docs.photoprism.app/user-guide/organize/archive/). Content that is archived is not deleted, but it does not appear in any area other than the archive. You can also have multiple instances, for example, one that contains all content while others have only a subset.
### Can you provide us with additional documentation?
Our Knowledge Base and User Guide provide additional information on product features and system requirements:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Quickstart Guide
URL: https://www.photoprism.app/pro/kb/quickstart/
> In this guide, we show you how to set up PhotoPrism® Pro in just a few steps and customize it to your needs.
Before you proceed, please make sure you have a customer account with us. You can register using the link you have [received from us by email](mailto:support@photoprism.app). If you already have an account, we will be happy to [assign your licenses](mailto:support@photoprism.app) to that account or give you [a free trial](mailto:sales@photoprism.app).
> [!NOTE]
> In case you already have our free [Community Edition](https://docs.photoprism.app/getting-started/) or [PhotoPrism Plus](/plus/) installed, you can follow the [Upgrade Guide](/pro/kb/upgrade/) to get started with PhotoPrism® Pro.
## System Requirements ##
We recommend hosting PhotoPrism Pro on a server with **at least 4 cores**, **8 GB of physical memory**, and a 64-bit operating system. It runs best with Docker Desktop on [Windows 10+](https://docs.docker.com/desktop/setup/install/windows-install/) and [macOS 11+](https://docs.docker.com/desktop/setup/install/mac-install/), [Podman](https://podman.io/) on Red Hat and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux, and [Docker](https://docs.docker.com/desktop/setup/install/linux/) on all other Linux distributions such as Ubuntu and Debian.
## Firewall Settings ##
In order to successfully set up your installation and view location details in PhotoPrism® Pro, you must **allow requests to Docker Hub and our geocoding API** if you have a firewall installed, and make sure your internet connection is working.
## Portainer Setup Guide ##
Portainer lets you manage Docker containers through a web interface. On many NAS devices it either comes pre-installed or you can install it from the vendor's app store.
## Setup Using Docker Compose ##
[Docker Compose](https://docs.docker.com/compose/) uses a [human-friendly YAML config file](https://docs.photoprism.app/developer-guide/technologies/yaml/) to specify all application services, so you can easily start them with a single command.
For this to work, make sure that you have [Docker and Docker Compose](https://docs.photoprism.app/getting-started/troubleshooting/docker/#installation) (Linux) or [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows) installed and running on your server before you continue. Be careful not to use an old Docker Enterprise version that Microsoft used to pre-install on Windows Server, as it is incompatible with modern Docker images. If your server does not yet support the new `docker compose` command, you can still use the legacy `docker-compose` command instead.
[Podman](https://podman.io/) is also [supported as a replacement for Docker](https://docs.photoprism.app/getting-started/troubleshooting/docker/#podman-compose) on Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux.
In case you are not sure if you have Docker installed yet, and if so, which version, you can run the following command in a terminal to display the version information:
```
docker --version
```
For users of Red Hat-based Linux distributions:
```
podman --version
```
**Windows** users should have the latest [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) installed. With Windows Pro, Server and Enterprise, [Hyper-V can be enabled](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) as an alternative, which Microsoft does not offer its Windows Home customers.
**Linux Kernel Security Modules** such as AppArmor and SELinux may [require additional configuration](https://docs.photoprism.app/getting-started/troubleshooting/docker/#kernel-security) if you want to use them. The application services may fail to start if they have insufficient permissions or privileges.
> [!NOTE]
> We can offer you alternative installation methods if needed. However, this method is the fastest and least error-prone for most operating systems and we generally recommend it unless there is a specific problem.
### Step 1: Customize Configuration ###
Download the *compose.yaml* default configuration for your operating system (right click and *Save Link As...*) to a local folder, e.g. `/opt/photoprism` on Linux, then open the file with a text editor to [customize the storage volumes](https://docs.photoprism.app/getting-started/docker-compose/#volumes) and [other options](/pro/kb/config-options/) as needed:
| | |
|-------------|--------------------------------------------------------------------------------------------------------------------------|
| **Windows** | [https://setup.photoprism.app/pro/windows/compose.yaml](https://setup.photoprism.app/pro/windows/compose.yaml) |
| **macOS** | [https://setup.photoprism.app/pro/macos/compose.yaml](https://setup.photoprism.app/pro/macos/compose.yaml) |
| **Ubuntu** | [https://setup.photoprism.app/pro/ubuntu/compose.yaml](https://setup.photoprism.app/pro/ubuntu/compose.yaml) |
| **Red Hat** | [https://setup.photoprism.app/pro/redhat/docker-compose.yml](https://setup.photoprism.app/pro/redhat/docker-compose.yml) |
Except for the additional features, PhotoPrism Pro is [configured in the same way](/pro/kb/config-options/) as PhotoPrism. You can therefore refer to our [official documentation](https://docs.photoprism.app/) for [basic settings](https://docs.photoprism.app/getting-started/docker-compose/#volumes) and [general setup instructions](https://docs.photoprism.app/getting-started/docker-compose/). When editing the configuration file, please note that related values must start at the same indentation level [in YAML files](https://docs.photoprism.app/developer-guide/technologies/yaml/) and that tabs are not allowed for indentation. We recommend using 2 spaces.
Please always change `PHOTOPRISM_ADMIN_PASSWORD` so that the app starts with a secure initial password. Never use easy-to-guess passwords or default values like "insecure" on publicly accessible servers. There is no default in case no password was provided. A minimum length of 8 characters is required.
> [!NOTE]
> If you want to start with an empty library, you can mount any directory that has enough free space for your needs.
### Step 2: Start PhotoPrism Pro ###
When you are done with the configuration, open a terminal and change to the folder where the *compose.yaml* file was saved.
Now run the following commands to pull the latest images from there, and then start MariaDB and PhotoPrism as background services:
```
docker compose pull
docker compose up -d
```
Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the `docker` and `docker compose` commands with `podman` and `podman-compose` as [drop-in replacements](https://docs.photoprism.app/getting-started/troubleshooting/docker/#podman-compose):
```
podman-compose pull
podman-compose up -d
```
After waiting a few moments, you should be able to open the user interface in a Web browser by navigating to:
👉 [**https://privatecloud.photos:2342/**](https://privatecloud.photos:2342/)
If you have modified the server hostname, port, or protocol in your configuration, the URL to use changes accordingly.
Other issues? Our [Troubleshooting Checklists](https://docs.photoprism.app/getting-started/troubleshooting/) help you quickly diagnose and solve them.
When you see the login screen, **sign in with the admin username and initial password** you specified in your *compose.yaml* file.
You can change it in the user interface when you navigate to *Settings > Account*. PhotoPrism® Pro also includes a [web user interface for creating additional accounts](https://docs.photoprism.app/user-guide/users/) and managing sessions.
> [!NOTE]
> Note that the examples in our documentation use the new `docker compose` command by default. If your server does not yet support it, the old `docker-compose` command will continue to work.
> [!NOTE]
> To verify that all services are running properly, you can view the server logs at any time by running `docker compose logs -f`.
### Step 3: Activate Your License ###
You can now follow these steps to [activate your license](/pro/kb/activation/) by connecting your instance to your customer account at [my.photoprism.app](https://my.photoprism.app/):
(1) From the main navigation, open *Settings* and click the *Evaluation / Non-Production Use* link in the footer. If you do not see this link, for example on mobile devices, you can manually navigate to */library/upgrade* in the browser toolbar.
(2) If you have already received an activation code, enter it and click *Activate* or click *Register* to sign up on our website and receive a code to connect your account.
(3) Finally, please restart your instance for the changes to take effect. You should now see the name of your company or organization in the footer of the *Settings* page instead of *Evaluation / Non-Production Use*. This means that your instance has been successfully activated for production use. Thank you very much!
### Step 4: Get Started ###
Our [First Steps 👣](https://docs.photoprism.app/user-guide/first-steps/) tutorial guides you through the user interface and library settings to ensure your library is indexed according to your individual preferences.
In the following section, we'll give you an overview of the available user roles in PhotoPrism® Pro and show you how to manage accounts.
#### User Management ####
In addition to the command-line interface available in all editions, PhotoPrism® Pro includes a web user interface for managing user accounts as well as additional account roles to restrict permissions as needed.
#### Authenticating Users Against a Directory Server ####
With the built-in LDAP support, you can authenticate users against a central [Lightweight Directory Access Protocol](https://ubuntu.com/server/docs/service-ldap) or [Active Directory (AD)](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-ldap) server so that users on the corporate network can sign in with their existing usernames and passwords.
#### Using Audit Logs ####
Audit logs help your security, auditing, and compliance entities monitor PhotoPrism® Pro for potential vulnerabilities, misuse, and other critical incidents.
#### Hardened Web Security ####
PhotoPrism® Pro additionally includes advanced security features such as session monitoring (run `photoprism auth --help` to see the available commands), which allows you to create, inspect and delete access tokens for authenticating browsers and other clients (including [app passwords](https://docs.photoprism.app/user-guide/settings/account/#apps-and-devices)). You can also set a general request rate limit for the built-in web server and a threshold for failed login attempts.
For more information on the available security options, see the *Authentication* and *Web Server* sections in our [configuration options](/pro/kb/config-options/) overview.
#### Using HTTPS ####
For **HTTPS** to work with your own domains, you can either [use an HTTPS reverse proxy like Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/) (that you might already have to run other services) or specify a TLS certificate and private key file via `PHOTOPRISM_TLS_CERT` and `PHOTOPRISM_TLS_KEY` in your *compose.yaml* file.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Release Notes
URL: https://www.photoprism.app/pro/kb/release-notes/
> Find out about the latest features and enhancements in our team editions for professional users.
### Build 1.2607.28 (July 28, 2026)
With this major new release, [equirectangular 360° photos and videos](https://github.com/photoprism/photoprism/issues/5623) can now be explored interactively. To preserve detail when zooming in, the maximum [thumbnail and video resolution has been increased to 16K](https://github.com/photoprism/photoprism/issues/5669).
A new [inline document viewer](https://github.com/photoprism/photoprism/issues/5488) makes it possible to read multi-page PDFs without downloading them first. Metadata enthusiasts benefit from enhanced XMP support, allowing GPS coordinates and face regions to be imported from both [XMP sidecar files](https://github.com/photoprism/photoprism/issues/5712) and [embedded XMP metadata](https://github.com/photoprism/photoprism/issues/5751). In addition, camera and lens make and model information can now be [edited through the CLI and API](https://github.com/photoprism/photoprism/issues/5663). Elsewhere, the Settings interface has been reorganized and now includes a dedicated Accessibility section, where you can, for example, prevent action menus from opening on hover. Album download and sorting options have moved to a new Collections tab.
[AI-related improvements](https://docs.photoprism.app/user-guide/ai/) include a [new `service_tier` option](https://github.com/photoprism/photoprism/issues/5725) for more cost-effective API requests, along with various [fixes and improvements for Ollama](https://github.com/photoprism/photoprism/issues/5728).
What's new?
- Viewer: [Added support for 360° panorama photos and videos](https://github.com/photoprism/photoprism/pull/5623) by [@omerdduran](https://github.com/omerdduran)
- Viewer: [Added an inline viewer for reading multi-page PDF documents](https://github.com/photoprism/photoprism/issues/5488) by [@omerdduran](https://github.com/omerdduran)
- AI: [Added `service_tier` setting for OpenAI-compatible service requests](https://github.com/photoprism/photoprism/issues/5725)
- AI: [Updated Ollama default settings and default cloud model](https://github.com/photoprism/photoprism/issues/5726)
- AI: [Improved Ollama caption and label quality by disabling reasoning output](https://github.com/photoprism/photoprism/issues/5728)
- AI: [Improved retry handling for rate-limited (HTTP 429) vision requests](https://github.com/photoprism/photoprism/issues/5729)
- AI: [Improved image reference validation for computer vision requests](https://github.com/photoprism/photoprism/issues/5734)
- AI: [Fixed a concurrency issue in the local TensorFlow classifier](https://github.com/photoprism/photoprism/issues/5694)
- UX: [Added a setting to prevent action menus from opening on hover](https://github.com/photoprism/photoprism/issues/5650) by [@lastzero](https://github.com/lastzero)
- UX: [Improved face-marker overlay performance and interaction](https://github.com/photoprism/photoprism/issues/5672) by [@omerdduran](https://github.com/omerdduran)
- UX: [Improved notification messages to appear in the current interface language](https://github.com/photoprism/photoprism/issues/5682)
- UX: [Fixed clearing the photo selection after saving batch edits](https://github.com/photoprism/photoprism/issues/5738)
- Auth: [Added a configurable OpenID Connect sign-in prompt to force re-authentication](https://github.com/photoprism/photoprism/issues/5698)
- Auth: [Added OpenID Connect RP-initiated logout to end the upstream provider session](https://github.com/photoprism/photoprism/issues/5684)
- Auth: [Fixed Cognito-issued ID token validation by sending a nonce during OIDC sign-in](https://github.com/photoprism/photoprism/issues/5695)
- Auth: [Fixed the OpenID Connect sign-in button not being translated](https://github.com/photoprism/photoprism/pull/5754)
- Auth: [Improved login, session, and OIDC error messages to appear in the current language](https://github.com/photoprism/photoprism/issues/5699)
- Auth: [Limited app passwords of accounts without web login to WebDAV sync](https://github.com/photoprism/photoprism/issues/5647) by [@lastzero](https://github.com/lastzero)
- People: [Added import of face regions from XMP sidecar files](https://github.com/photoprism/photoprism/issues/5712) by [@omerdduran](https://github.com/omerdduran)
- People: [Added import of face regions from embedded XMP metadata](https://github.com/photoprism/photoprism/issues/5751) by [@omerdduran](https://github.com/omerdduran)
- People: [Added a type-ahead cache for faster name suggestions](https://github.com/photoprism/photoprism/issues/5666) by [@lastzero](https://github.com/lastzero)
- Places: [Fixed stacking of photos at the same location when zoomed in](https://github.com/photoprism/photoprism/issues/5643)
- Albums: [Fixed download of sidecar files when the option is enabled](https://github.com/photoprism/photoprism/issues/5743)
- Albums: [Fixed single file downloads from a shared folder, moment, calendar, or region](https://github.com/photoprism/photoprism/issues/5727)
- Albums: [Fixed error when creating a share link as a non-admin user](https://github.com/photoprism/photoprism/issues/5748)
- Folders: [Fixed search results not including pictures from subdirectories](https://github.com/photoprism/photoprism/issues/5724)
- Batch Edit: [Fixed the sorting of pictures in searches after editing dates](https://github.com/photoprism/photoprism/issues/5739)
- Settings: [Added a "Collections" tab to configure download settings](https://github.com/photoprism/photoprism/issues/848) by [@omerdduran](https://github.com/omerdduran)
- Settings: [Added 16K thumbnail and video size support for 360° media](https://github.com/photoprism/photoprism/issues/5669) by [@lastzero](https://github.com/lastzero)
- Settings: [Reorganized interface with a new accessibility section](https://github.com/photoprism/photoprism/issues/5429) by [@omerdduran](https://github.com/omerdduran)
- Index: [Added a fallback to embedded JPEG previews for unsupported files](https://github.com/photoprism/photoprism/issues/5673)
- Index: [Added native JPEG XL decoding as an alternative to the external `djxl` tool](https://github.com/photoprism/photoprism/issues/5693)
- Index: [Fixed duplicate creation when identical files are indexed in parallel](https://github.com/photoprism/photoprism/issues/5652) by [@knowald](https://github.com/knowald)
- Index: [Improved indexing to record original file names only for imported files](https://github.com/photoprism/photoprism/issues/5668)
- Metadata: [Added extraction of GPS coordinates from XMP sidecar files](https://github.com/photoprism/photoprism/issues/4106) by [@omerdduran](https://github.com/omerdduran)
- Metadata: [Added Lens Make and Model updates via CLI and API](https://github.com/photoprism/photoprism/issues/5656) by [@keif888](https://github.com/keif888)
- Metadata: [Added Camera Make and Model updates via CLI and API](https://github.com/photoprism/photoprism/issues/5663) by [@lastzero](https://github.com/lastzero)
- Metadata: [Improved support for metadata from XMP sidecar files](https://github.com/photoprism/photoprism/pull/5563) by [@omerdduran](https://github.com/omerdduran)
- Metadata: [Improved XMP handling to map `dc:subject` to the Subject field](https://github.com/photoprism/photoprism/issues/2075)
- PWA: [Added glass, mint, neon, and rainbow app icons and full-bleed touch variants](https://github.com/photoprism/photoprism/issues/5737)
- PWA: [Improved the app manifest with maskable icons, language, and screenshots](https://github.com/photoprism/photoprism/issues/5691)
- PWA: [Fixed using the configured app icon as the iOS Home Screen icon](https://github.com/photoprism/photoprism/issues/5737)
- CLI: [Improved role and auth-provider usage descriptions](https://github.com/photoprism/photoprism/issues/5667) by [@lastzero](https://github.com/lastzero)
- CLI: [Fixed `auth add` command when the database runs with `NO_ZERO_DATE` enabled](https://github.com/photoprism/photoprism/issues/5707)
- API: [Added an `X-Count` header to label and service search responses](https://github.com/photoprism/photoprism/issues/5649) by [@keif888](https://github.com/keif888)
- WebDAV: [Fixed uploads reporting success even when they failed](https://github.com/photoprism/photoprism/issues/5745)
- WebDAV: [Improved uploads to skip videos and RAW files when raw and video sync is off](https://github.com/photoprism/photoprism/issues/5744)
- WebDAV: [Fixed routine sync-client folder checks being logged as errors](https://github.com/photoprism/photoprism/issues/5715)
- Storage: [Fixed a path lookup error when resolving filesystem locations](https://github.com/photoprism/photoprism/issues/5683)
- Storage: [Added automatic expiry for temporary download archives](https://github.com/photoprism/photoprism/commit/4bcd670c5)
- Database: [Improved error logging to capture connection issues](https://github.com/photoprism/photoprism/issues/5637)
- Database: [Upgraded config examples from MariaDB 11.8 to 12.3 (LTS)](https://github.com/photoprism/photoprism/issues/5705)
- Database: [Fixed byte truncation to be rune-safe for all text columns](https://github.com/photoprism/photoprism/issues/5638)
- Docker: [Removed per-user skeleton files to reduce the image size](https://github.com/photoprism/photoprism/issues/5154) by [@alexisLefebvre](https://github.com/alexisLefebvre)
- Helm: [Added support for external database password secrets](https://github.com/photoprism/photoprism/issues/5661) by [@kurczynski](https://github.com/kurczynski)
- Security: [Added a feature flag to disable app passwords](https://github.com/photoprism/photoprism/issues/5647) by [@lastzero](https://github.com/lastzero)
- Security: [Added signed download tokens and improved preview token handling](https://github.com/photoprism/photoprism/issues/5733)
- Security: [Hardened WebDAV syncing, indexing](https://github.com/photoprism/photoprism/issues/5735), and [file locking](https://github.com/photoprism/photoprism/issues/5736)
- Security: [Upgraded `libheif` from v1.22.2 to v1.23.1 (CVE-2026-50142)](https://github.com/photoprism/photoprism/issues/5653)
- Security: [Upgraded Go from v1.26.3 to v1.26.5](https://github.com/golang/go/issues?q=milestone%3AGo1.26.5) and [ONNX Runtime to v1.26.0](https://github.com/photoprism/photoprism/commit/1fad248031eca0ae80f1bb7b122535e79852558b)
- Translations: [Improved French](https://docs.photoprism.app/developer-guide/translations-weblate/) by [@jean-louis67](https://github.com/jean-louis67), and [Hebrew](https://docs.photoprism.app/developer-guide/translations-weblate/) by [@avma](https://github.com/avma)
> [!NOTE]
> We recommend performing a [complete rescan](https://docs.photoprism.app/user-guide/library/originals/) of your library after upgrading to benefit from the improvements. Please note that manually marking faces on 360° content is not yet supported in this release.
> [!NOTE]
> Missing [user interface translations](https://translate.photoprism.app/engage/photoprism/) have been generated with the help of DeepL and Google Translate. Native speakers are [welcome to help us improve them](https://docs.photoprism.app/developer-guide/translations-weblate/) where needed.
### Build 1.2606.01 (June 1, 2026)
This service release includes important security and reliability updates. As an additional safety measure, indexing, importing, and uploading can be disabled when [free disk space falls below a configurable threshold](https://docs.photoprism.app/user-guide/library/originals/#free-storage-threshold) to prevent storage volumes from filling up.
What's new?
- Index: [Optional free disk space threshold prevents storage from filling up](https://github.com/photoprism/photoprism/issues/5613)
- Index: [Fixed recovery of hidden stacks whose primary image was replaced](https://github.com/photoprism/photoprism/issues/5625)
- Videos: [Improved hardware transcoding setup and documentation](https://github.com/photoprism/photoprism/issues/5631)
- Videos: [Fixed VAAPI transcoding for compatibility with FFmpeg 8](https://github.com/photoprism/photoprism/issues/5630)
- Videos: [Added an option to exclude formats from FFmpeg processing](https://github.com/photoprism/photoprism/issues/5617)
- Thumbs: [PNGs are exported without an ICC profile if `libpng` rejects it](https://github.com/photoprism/photoprism/issues/5616)
- Folders: [Fixed recurring deletion and re-creation of folder albums](https://github.com/photoprism/photoprism/issues/5615)
- Security: [Reinforced user profile endpoint authorization checks](https://github.com/photoprism/photoprism/issues/5619) by [@geo-chen](https://github.com/geo-chen)
- Security: [Removed Pebble binary from Ubuntu base images (CVE-2026-39821)](https://github.com/photoprism/photoprism/issues/5620)
- Security: [Upgraded `libheif` from v1.21.2 to v1.22.2 (17 CVE fixes)](https://github.com/photoprism/photoprism/issues/5621)
### Build 1.2605.23 (May 23, 2026)
This update introduces a redesigned [Info Sidebar](https://docs.photoprism.app/user-guide/organize/info-sidebar/) that lets you [edit metadata, albums, and labels](https://github.com/photoprism/photoprism/issues/4966) as well as [manually tag faces](https://github.com/photoprism/photoprism/issues/1548) without leaving the full-screen viewer. On the AI side, our ONNX-based face recognition pipeline has fully [replaced the legacy Pigo detector](https://github.com/photoprism/photoprism/issues/5508), and the [`vision.yml`](https://docs.photoprism.app/user-guide/ai/#visionyml-reference) configuration now accepts [mixed-case model names](https://github.com/photoprism/photoprism/issues/5594) so all identifiers from Hugging Face, Ollama, and OpenAI-compatible catalogs can be used.
Media handling has been thoroughly modernized: video transcoding now supports [Vulkan hardware acceleration via FFmpeg 8](https://github.com/photoprism/photoprism/issues/5592), images use a [native HEIC/AVIF reader](https://github.com/photoprism/photoprism/issues/5509) (with `libheif` upgraded to v1.21.2), and [layered TIFF and Adobe Photoshop PSD](https://github.com/photoprism/photoprism/issues/5383) files are now supported. Other highlights include [NOT & AND operators in the label filter](https://github.com/photoprism/photoprism/issues/5535), a [drag-and-drop file upload zone](https://github.com/photoprism/photoprism/issues/1216), [`zstd` compression](https://github.com/photoprism/photoprism/issues/5550) for faster page loads, [hardened WebDAV interoperability](https://github.com/photoprism/photoprism/issues/3541), and a new Ubuntu 26.04 LTS base image.
What's new?
- Viewer: [Sidebar shows editable metadata, albums, and labels](https://github.com/photoprism/photoprism/issues/4966) by [@omerdduran](https://github.com/omerdduran)
- Viewer: [Captions can be hidden using the menu or a keyboard shortcut](https://github.com/photoprism/photoprism/issues/5580)
- Faces: [Viewer sidebar allows to manually tag faces on pictures](https://github.com/photoprism/photoprism/issues/1548) by [@omerdduran](https://github.com/omerdduran)
- Faces: [Dropped legacy Pigo detector in favor of ONNX-based detection](https://github.com/photoprism/photoprism/issues/5508)
- UX: [Added a drag-and-drop zone to the file upload dialog](https://github.com/photoprism/photoprism/issues/1216)
- UX: [Improved form input validation and numeric range caps](https://github.com/photoprism/photoprism/issues/5584)
- Login: [Enhanced login page with "Stay signed in on this device" toggle](https://github.com/photoprism/photoprism/issues/5476)
- Login: [OIDC provider initialization is retried after transient discovery failure](https://github.com/photoprism/photoprism/issues/5478)
- Login: [Fixed OIDC redirect of unauthenticated users when opening direct links](https://github.com/photoprism/photoprism/issues/5506)
- Search: [Improved label filter with support for NOT & AND operators](https://github.com/photoprism/photoprism/issues/5535)
- Labels: [Added support for homophones and homophone-aware lookups](https://github.com/photoprism/photoprism/issues/5227) by [@keif888](https://github.com/keif888)
- Labels: [Fixed duplicates when renaming a label and re-adding the previous name](https://github.com/photoprism/photoprism/issues/5531)
- Labels: [Fixed case and punctuation variants creating duplicates in the edit dialog](https://github.com/photoprism/photoprism/issues/5532)
- Folders: [Child folders with emoji paths no longer overwrite parent albums](https://github.com/photoprism/photoprism/issues/5366)
- Videos: [Added support for Vulkan hardware transcoding using FFmpeg 8](https://github.com/photoprism/photoprism/issues/5592)
- Videos: [HEVC remux output is tagged as `hvc1` based on MP4 chunk scan](https://github.com/photoprism/photoprism/issues/5593)
- Images: [Added support for layered TIFF and Adobe Photoshop PSD images](https://github.com/photoprism/photoprism/issues/5383)
- Images: [Added native HEIC/AVIF reader and upgraded `libheif` to v1.21.2](https://github.com/photoprism/photoprism/issues/5509)
- Images: [Replaced `disintegration/imaging` library with native format support](https://github.com/photoprism/photoprism/issues/5353)
- Server: [Added `zstd` compression support for faster loading times](https://github.com/photoprism/photoprism/issues/5550)
- Server: [Added pre-compressed frontend bundles for faster loading times](https://github.com/photoprism/photoprism/issues/5552)
- Server: [Fixed nil-DB race in async count and cover update goroutines](https://github.com/photoprism/photoprism/issues/5551)
- WebDAV: [Hardened timeouts, cancellation, and Depth-1 fallback diagnostics](https://github.com/photoprism/photoprism/issues/5474)
- WebDAV: [Fixed settings dialog to allow credentials for existing services to be changed](https://github.com/photoprism/photoprism/issues/5558)
- WebDAV: [Added fallback for servers that only allow `PROPFIND` with a Depth of 1](https://github.com/photoprism/photoprism/issues/3541)
- CLI: [Improved `vision run` command updates sidecar YAML files](https://github.com/photoprism/photoprism/issues/5493)
- CLI: [Added a `faces config` subcommand to list face-related options](https://github.com/photoprism/photoprism/issues/5597)
- CLI: [Fixed flags placed after positional arguments being silently dropped](https://github.com/photoprism/photoprism/issues/5604)
- MCP: [Added read-only support for the Model Context Protocol (MCP)](https://github.com/photoprism/photoprism/issues/5024)
- MCP: [Added `--disable-mcp` flag to disable Model Context Protocol support](https://github.com/photoprism/photoprism/issues/5536)
- Config: [Removed limitation for vision model names to be lowercased](https://github.com/photoprism/photoprism/issues/5594)
- Config: [Improved worker auto-configuration based on number of CPU cores](https://github.com/photoprism/photoprism/issues/5567)
- Config: [Consolidated SQL driver names and parsing in `pkg/dsn`](https://github.com/photoprism/photoprism/issues/5588) by [@keif888](https://github.com/keif888)
- Config: [Default HTTP and HTTPS ports are stripped from base URLs](https://github.com/photoprism/photoprism/issues/5590)
- Logs: [Information about long-running processes is logged](https://github.com/photoprism/photoprism/pull/5481) by [@keif888](https://github.com/keif888)
- Docker: [Upgraded base image to Ubuntu 26.04 LTS (Resolute Raccoon)](https://github.com/photoprism/photoprism/issues/5543)
- Security: [Search queries now use parameterized statements for all user input](https://github.com/photoprism/photoprism/issues/5587)
- Security: Upgraded Go from v1.26 to v1.26.3 and [ONNX Runtime to v1.25.1](https://github.com/photoprism/photoprism/issues/5555)
### Build 1.2603.05 (March 5, 2026)
This service release focuses on security hardening, interoperability improvements, and bug fixes to create a stable platform for upcoming features. 🔧
Ollama users benefit from [easier configuration](https://docs.photoprism.app/user-guide/ai/using-ollama/) with the `OLLAMA_BASE_URL` and `OLLAMA_API_KEY` environment variables, as well as improved fallback response handling for [caption generation](https://docs.photoprism.app/user-guide/ai/ollama-models/#caption-prompts) with reasoning models. To improve reliability, we addressed edge cases in [indexing](https://docs.photoprism.app/user-guide/library/originals/), [Places](https://docs.photoprism.app/user-guide/organize/places/) (GPS boundary overshoots), [folder albums](https://docs.photoprism.app/user-guide/organize/folders/) (emoji and slug collisions), [thumbnails](https://docs.photoprism.app/user-guide/settings/advanced/#preview-images), [metadata parsing](https://docs.photoprism.app/user-guide/library/metadata/), [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/) response headers, CLI validation, [OIDC](https://docs.photoprism.app/getting-started/advanced/openid-connect/) compatibility, and shared-domain hosting.
What's new?
- Ollama: [Added support for configuration via `OLLAMA_BASE_URL` and `OLLAMA_API_KEY`](https://github.com/photoprism/photoprism/issues/5361)
- Ollama: [Added a "thinking" response fallback for captions](https://github.com/photoprism/photoprism/issues/5455) by [@lastzero](https://github.com/lastzero)
- Index: [Fixed merged photos keeping image type after video file merges](https://github.com/photoprism/photoprism/issues/5418)
- Places: [Fixed handling of minor GPS coordinate overshoots near map boundaries](https://github.com/photoprism/photoprism/issues/5445)
- Folders: [Fixed emoji subfolders conflicting with parent folder albums](https://github.com/photoprism/photoprism/issues/5366)
- Folders: [Fixed folder album path collisions caused by truncated slugs](https://github.com/photoprism/photoprism/issues/5437)
- Library: [Hidden results now display file error reasons in Card and List views](https://github.com/photoprism/photoprism/issues/5391)
- Thumbs: [Fixed error buffer handling when interop index was missing](https://github.com/photoprism/photoprism/issues/5389)
- Metadata: [Clamped invalid Google JSON GPS coordinates to geo bounds](https://github.com/photoprism/photoprism/issues/5373)
- WebDAV: [Hardened response headers for interoperability](https://github.com/photoprism/photoprism/issues/5472) by [@lastzero](https://github.com/lastzero)
- CLI: [Standardized input path validation and exit codes](https://github.com/photoprism/photoprism/issues/5457) by [@lastzero](https://github.com/lastzero)
- SQLite: [Improved compatibility with Google OIDC identity provider](https://github.com/photoprism/photoprism/issues/4951) by [@keif888](https://github.com/keif888)
- Server: [Added HTTP security hardening config options](https://github.com/photoprism/photoprism/issues/5471) by [@lastzero](https://github.com/lastzero)
- Server: [Improved configuration and performance of Gzip route exclusions](https://github.com/photoprism/photoprism/issues/5384)
- Server: [Resolved known issues when hosting on a shared domain](https://github.com/photoprism/photoprism/issues/2391)
- Logs: [Fixed handling of missing caption thumbnails and video remux errors](https://github.com/photoprism/photoprism/issues/5398)
- Security: Upgraded Go to v1.26, which includes fixes and improvements
- Translations: [Updated French, German, Latvian, and Romanian](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2511.30 (November 30, 2025)
This major update introduces the long-awaited [Batch Edit](https://docs.photoprism.app/user-guide/organize/batch-edit/) dialog, which allows you to [edit the metadata of multiple pictures](https://docs.photoprism.app/user-guide/organize/batch-edit/) in one go. On the AI side, an [upgraded face recognition pipeline](https://docs.photoprism.app/user-guide/ai/face-recognition/) delivers more and better matches. PhotoPrism now integrates directly with [Ollama](https://docs.photoprism.app/user-guide/ai/using-ollama/) and [OpenAI](https://docs.photoprism.app/user-guide/ai/using-openai/) to generate [captions and labels](https://docs.photoprism.app/user-guide/ai/). Support for [custom TensorFlow models](https://docs.photoprism.app/developer-guide/vision/tensorflow/custom-models/), [refined configuration](https://docs.photoprism.app/user-guide/ai/#visionyml-reference), and [new scheduling options](https://docs.photoprism.app/user-guide/ai/#run-modes) offer further flexibility.
You'll also notice many performance and usability enhancements, such as the ability to [change the cover image for a person](https://docs.photoprism.app/user-guide/organize/people/#change-cover-for-a-person), as well as updated dependencies and new translations.
Upgrade Notes
- To benefit from the [facial recognition improvements](https://docs.photoprism.app/user-guide/ai/face-recognition/), we recommend running `photoprism faces audit --fix` and `photoprism faces index` [in a terminal](https://docs.photoprism.app/getting-started/docker-compose/#opening-a-terminal) to resolve any inconsistencies before detecting and matching additional faces. If you want the new engine to re-detect all faces for a clean state, you can do so by executing the commands `photoprism faces reset -f` and then `photoprism faces index` (after that, all detected faces must be reassigned). A [complete rescan](https://docs.photoprism.app/user-guide/library/originals/#when-should-complete-rescan-be-selected) will also detect additional faces, but takes longer since more indexing tasks are performed.
- PhotoPrism now [supports multiple AI engines](https://docs.photoprism.app/user-guide/ai/#model-engines), so the `PHOTOPRISM_DISABLE_TENSORFLOW` option [has been deprecated](https://github.com/photoprism/photoprism/issues/5310). You can still disable individual AI features using the [`PHOTOPRISM_DISABLE_*` feature flags](https://docs.photoprism.app/getting-started/config-options/#feature-flags) and/or a [custom `vision.yml`](https://docs.photoprism.app/user-guide/ai/#visionyml-reference) configuration.
What's new?
- AI: [Support for custom TensorFlow image classification models](https://github.com/photoprism/photoprism/pull/5011) by [@raystlin](https://github.com/raystlin)
- AI: [Direct Ollama integration for generating captions](https://github.com/photoprism/photoprism/issues/5123) and [labels](https://github.com/photoprism/photoprism/issues/5232) by [@lastzero](https://github.com/lastzero)
- AI: [Generate Captions & Labels using the OpenAI Responses API](https://github.com/photoprism/photoprism/issues/5322) by [@lastzero](https://github.com/lastzero)
- AI: [Improved face detection and embedding pipeline with a new CNN engine](https://github.com/photoprism/photoprism/issues/5167)
- AI: [Improved model configuration and `photoprism vision run` command](https://github.com/photoprism/photoprism/commit/4bc9cd6ca23bb65072b766ae16b7966b4e7b3e36)
- AI: [Added scheduling options for running vision models in the background](https://github.com/photoprism/photoprism/issues/5234)
- UX: [Added a batch edit dialog to edit multiple pictures at once](https://github.com/photoprism/photoprism/issues/271)
- UX: [Added a menu to select a cover image for people](https://github.com/photoprism/photoprism/issues/4151) by [@omerdduran](https://github.com/omerdduran)
- UX: ["Add to Album" dialog allows selection of multiple albums](https://github.com/photoprism/photoprism/pull/5177) by [@omerdduran](https://github.com/omerdduran)
- UX: [Improved people name editing and focus management](https://github.com/photoprism/photoprism/pull/5307) by [@omerdduran](https://github.com/omerdduran)
- UX: [Improved window scroll position restoration when navigating](https://github.com/photoprism/photoprism/issues/5211)
- UX: [Disabled autofocus on mobile devices to prevent keyboard from opening](https://github.com/photoprism/photoprism/issues/5213)
- UX: [Added a browser capability check displaying a warning if unsupported](https://github.com/photoprism/photoprism/issues/5047)
- UX: [Improved memory and event management in Viewer](https://github.com/photoprism/photoprism/issues/5260) and [Places](https://github.com/photoprism/photoprism/issues/5259)
- Auth: [2FA can be activated, even if the recovery code cannot be copied](https://github.com/photoprism/photoprism/issues/5106)
- OIDC: [Added support for Microsoft Entra ID security groups](https://github.com/photoprism/photoprism/issues/5334)
- Search: [Added escaping for `|` and `&` in filters](https://github.com/photoprism/photoprism/pull/5188) by [@keif888](https://github.com/keif888)
- Search: [Improved Boolean value parsing in filters](https://github.com/photoprism/photoprism/pull/5191) by [@keif888](https://github.com/keif888)
- Index: [Selecting "Complete Rescan" refreshes the detected media types](https://github.com/photoprism/photoprism/issues/5096)
- Index: [Underlying errors are logged when file type detection fails](https://github.com/photoprism/photoprism/issues/5149)
- Index: [Improved error logging when PDF documents cannot be indexed](https://github.com/photoprism/photoprism/issues/5166)
- Index: [Fixed in-memory photo and file lookup tables to prevent file rescans](https://github.com/photoprism/photoprism/issues/5235)
- Thumbs: [Embedding of ICC profiles based on InteropIndex](https://github.com/photoprism/photoprism/pull/5178) by [@akdor1154](https://github.com/akdor1154)
- Videos: [Fixed issues with non-keyframes when extracting still images](https://github.com/photoprism/photoprism/issues/5189)
- Intel QSV: [`libvpl2` will be installed when `PHOTOPRISM_INIT` includes "intel"](https://github.com/photoprism/photoprism/discussions/5098)
- API: [Added a force flag to the `DELETE /api/v1/albums/UID` endpoint](https://github.com/photoprism/photoprism/issues/5122)
- API: [Corrected handling of CORS preflight requests](https://github.com/photoprism/photoprism/issues/5133) by [@techmatt101](https://github.com/techmatt101)
- API: [Configured service key can be used for Vision API authentication](https://github.com/photoprism/photoprism/issues/5299)
- API: [`/api/v1/metrics` endpoint reports file system and account usage](https://github.com/photoprism/photoprism/issues/5355)
- Config: [`PHOTOPRISM_DISABLE_FRONTEND` disables the web user interface](https://github.com/photoprism/photoprism/issues/5111)
- CLI: [Added `--json` output format flag to `photoprism show` commands](https://github.com/photoprism/photoprism/issues/5220)
- CLI: [Added `vision reset` command to regenerate captions and labels](https://github.com/photoprism/photoprism/issues/5233)
- CLI: [Improved `photoprism dl` command to support additional flags](https://github.com/photoprism/photoprism/issues/5261)
- Setup: [Added `ollama` service to `compose.yaml` configuration examples](https://dl.photoprism.app/docker/)
- PWA: [Replaced "@lcdp/offline-plugin" with "workbox-webpack-plugin"](https://github.com/photoprism/photoprism/issues/5274)
- Docker: [Upgraded to Ubuntu 25.10](https://github.com/photoprism/photoprism/issues/5276), incl. [ExifTool v13.25](https://github.com/exiftool/exiftool/blob/master/Changes) and [libheif v1.20.2](https://github.com/strukturag/libheif/releases/tag/v1.20.2)
- Docker: [Preinstalled `libmagic-mgc` package for file type detection](https://github.com/photoprism/photoprism/issues/5149)
- Docker: [Improved `cmd.sh` script to terminate child processes](https://github.com/photoprism/photoprism/pull/5172) by [@keif888](https://github.com/keif888)
- Security: Upgraded Go to v1.25.4, which includes fixes and improvements
- Translations: [Updated Spanish and Vietnamese](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2507.07 (July 7, 2025)
This release adds support for using [Ollama models in the Vision AI service](https://github.com/photoprism/photoprism-vision/pull/5), improves search performance, and [introduces an "Adjust Location" dialog](https://github.com/photoprism/photoprism/issues/465) for setting photo coordinates on a map. Users can now [delete albums from the toolbar](https://github.com/photoprism/photoprism/issues/4994) and customize the [language of location details](https://github.com/photoprism/photoprism/issues/883). Video and metadata handling have been refined, with updates to [transcoding](https://github.com/photoprism/photoprism/issues/4969), scanner detection, and [CLI tools](https://github.com/photoprism/photoprism/issues/4982). A fix for [SQLite index updates](https://github.com/photoprism/photoprism/issues/3742) is also included. [Batch editing](https://github.com/photoprism/photoprism/issues/271) features are in final development and will be available in an upcoming release.
What's new?
- AI: [Added Ollama model and data URL support to the Vision Service](https://github.com/photoprism/photoprism-vision/pull/5)
- Auth: [Added a new "Manager" role that grants read-only access to the user management](https://www.photoprism.app/pro/kb/roles/)
- UX: [Added "Adjust Location" dialog to set coordinates on a map](https://github.com/photoprism/photoprism/issues/465)
- UX: [Added "Delete Album" action to the album toolbar menu](https://github.com/photoprism/photoprism/issues/4994)
- UX: [Optimized thumbnail rendering performance in result views](https://github.com/photoprism/photoprism/issues/4985)
- Places: [Added a config option to set the language of location details](https://github.com/photoprism/photoprism/issues/883)
- Viewer: [Fixed timezone handling in the information sidebar](https://github.com/photoprism/photoprism/pull/5015)
- Viewer: [Seeking disables looping when playing a short video](https://github.com/photoprism/photoprism/commit/1709f708edbd44ea8dda02cc3f343330f7779836)
- Videos: [Added config options for transcoding preset, quality, and device](https://github.com/photoprism/photoprism/issues/4969)
- Videos: [Fixed playback when using QSV to transcode HEVC files](https://github.com/photoprism/photoprism/issues/5040)
- Videos: [Short videos up to 3 seconds are no longer classified as Live Photos](https://github.com/photoprism/photoprism/issues/5089)
- Motion Photos: [Fixed playback of videos embedded in Samsung HEIF files](https://github.com/photoprism/photoprism/issues/5027)
- Metadata: [Updated list of unwanted descriptions](https://github.com/photoprism/photoprism/pull/5078)
- Metadata: [Improved scanner detection based on device make and model](https://github.com/photoprism/photoprism/issues/5073)
- Metadata: [Fixed an issue that prevented changing the day to "Unknown" in February](https://github.com/photoprism/photoprism/issues/5038)
- Labels: [Updated Animal and Snow label category assignments](https://github.com/photoprism/photoprism/issues/5057)
- Upload: [Improved token used to distinguish simultaneous uploads](https://github.com/photoprism/photoprism/issues/4970)
- CLI: [Added `photoprism dl` command to import media from a URL](https://github.com/photoprism/photoprism/issues/4982)
- CLI: [Fixed an error in the backup command when a custom filename is specified](https://github.com/photoprism/photoprism/issues/5088)
- API: [Added a Content-Type header to the metrics endpoint](https://github.com/photoprism/photoprism/pull/5042)
- API: [Authorized clients are allowed to create album share links](https://github.com/photoprism/photoprism/issues/4973)
- SQLite: [Fixed "'too many SQL variables'" error on index updates](https://github.com/photoprism/photoprism/issues/3742)
- Security: Updated Go to v1.24.4, which includes fixes and improvements
- Translations: [Updated Arabic, French, German, and Japanese](https://github.com/photoprism/photoprism/discussions/4980)
### Build 1.2504.26 (April 26, 2025)
This release includes a long list of enhancements and new features, many of them contributed by our community. Most notably, [performance has been significantly improved](https://github.com/photoprism/photoprism/issues/4778) in [many areas](https://github.com/photoprism/photoprism/pull/4323), we have added [a collapsible info sidebar](https://github.com/photoprism/photoprism/issues/4812) to the fullscreen viewer, it is possible to [choose a specific picture as album cover](https://github.com/photoprism/photoprism/issues/383), and you can [configure computer vision tasks](https://github.com/photoprism/photoprism/issues/1090) like image classification to [use an external service](https://github.com/photoprism/photoprism/issues/1090#issuecomment-2800728541) for [improved scalability](https://github.com/photoprism/photoprism/issues/98) and [customization](https://github.com/photoprism/photoprism/issues/127).
Important Changes
- To take advantage of the [performance improvements in TensorFlow 2](https://github.com/photoprism/photoprism/issues/222), users of [our Docker images](https://hub.docker.com/r/photoprism/pro/tags) can set the [`PHOTOPRISM_INIT`](https://docs.photoprism.app/getting-started/config-options/#docker-image) variable to `"tensorflow"`. This will automatically detect, download, and [install a version of TensorFlow](https://github.com/photoprism/photoprism/blob/develop/scripts/dist/install-tensorflow.sh) optimized for your CPU.
- If you are using a [custom user interface theme](/pro/kb/customization/), you may be excited to hear that this release includes additional customization options that allow you to specify the icon as a theme variable, add or update multiple themes, change the login footer text, and configure a custom site favicon. [Learn more ›](/pro/kb/customization/)
What's new?
- AI: [Upgraded Google TensorFlow from v1.15.2 to v2.18.0](https://github.com/photoprism/photoprism/issues/222) by [@raystlin](https://github.com/raystlin)
- AI: [Vision API allows remote use of other instances and models](https://github.com/photoprism/photoprism/issues/1090)
- UX: [Reduced frontend bundle size by 54% for faster loading](https://github.com/photoprism/photoprism/issues/4778) by [@AsikNasik](https://github.com/AsikNasik)
- UX: [Asynchronous updates improve backend responsiveness](https://github.com/photoprism/photoprism/pull/4323) by [@tschechniker](https://github.com/tschechniker)
- UX: [Arrow keys can be used to navigate in the Edit dialog](https://github.com/photoprism/photoprism/pull/3623) by [@tomplast](https://github.com/tomplast)
- UX: [Added additional keyboard shortcuts with usage hints in action menus](https://github.com/photoprism/photoprism/issues/1131)
- UX: [Improved focus management for more reliable keyboard event handling](https://github.com/photoprism/photoprism/issues/4916)
- UX: [Disabled animation when refreshing search results to prevent flickering](https://github.com/photoprism/photoprism/issues/4917)
- UX: [User interface language can be changed on the login page](https://github.com/photoprism/photoprism/issues/4942)
- UX: [Fixed incorrect spelling in log messages](https://github.com/photoprism/photoprism/pull/4506) by [@yarikoptic](https://github.com/yarikoptic)
- People: [Improved performance and strategy for manual tagging](https://github.com/photoprism/photoprism/issues/3124) by [@theshadow27](https://github.com/theshadow27)
- Search: [Find pictures with specific or no terms in Title and Caption](https://github.com/photoprism/photoprism/issues/4947)
- Search: [Result views are reset when there are no matches or an error occurs](https://github.com/photoprism/photoprism/issues/4935)
- Viewer: [Added a collapsible sidebar for displaying metadata](https://github.com/photoprism/photoprism/issues/4812) by [@omerdduran](https://github.com/omerdduran)
- Viewer: [Added a new menu control in the top bar for additional actions](https://github.com/photoprism/photoprism/issues/4811)
- Viewer: [Added "Set as Album Cover" and Archive/Restore actions to the menu](https://github.com/photoprism/photoprism/issues/383)
- Viewer: [Fixed opening pictures from randomly sorted search results](https://github.com/photoprism/photoprism/issues/4905)
- Viewer: [Optimized thumbnail size selection for high aspect ratios](https://github.com/photoprism/photoprism/issues/4927)
- Videos: [Transcoding creates fragmented MP4s optimized for streaming](https://github.com/photoprism/photoprism/issues/4892)
- Videos: [Fixed Intel Quick Sync Video (QSV) hardware transcoding](https://github.com/photoprism/photoprism/pull/4382) by [@hicasper](https://github.com/hicasper)
- Videos: [Fixed transcoding hardware driver installation for Intel QSV](https://github.com/photoprism/photoprism/issues/4967)
- Videos: [Improved transcoding and indexing logs](https://github.com/photoprism/photoprism/pull/4549) by [@Akashic101](https://github.com/Akashic101)
- Places: [Improved styles, colors, and mountain shading of the default world map](https://github.com/photoprism/photoprism/issues/4959)
- Upload: [Added support for uploading multiple pictures as a zip archive](https://github.com/photoprism/photoprism/issues/4929)
- Upload: [File extensions and total size of Web uploads can be restricted](https://github.com/photoprism/photoprism/issues/4895)
- Import: [Hidden `.keep` and `.gitkeep` files are preserved](https://github.com/photoprism/photoprism/pull/4092) by [@zhzy0077](https://github.com/zhzy0077)
- WebDAV: [Added `Depth` header to improve service discovery](https://github.com/photoprism/photoprism/pull/4608) by [@esteve](https://github.com/esteve)
- Config: [Passwords and secrets can be read from files](https://github.com/photoprism/photoprism/pull/2302) by [@petertrr](https://github.com/petertrr)
- Setup: [Improved inline documentation in compose.yaml examples](https://github.com/photoprism/photoprism/issues/4051)
- Docker: [Upgraded Ubuntu 25.04 (Plucky Puffin) base image includes FFmpeg v7.1.1, Darktable v5.0.1, RawTherapee v5.11, ExifTool v13.10](https://github.com/photoprism/photoprism/issues/4953), and [libheif v1.19.7](https://github.com/strukturag/libheif/releases/tag/v1.19.7)
- Security: Go has been upgraded to v1.24.2, which includes fixes and improvements
- Translations: [Updated Arabic, French, and German](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2503.21 (March 21, 2025)
This release includes some major usability enhancements, [PDF file format support](https://github.com/photoprism/photoprism/issues/4600), the latest [translations contributed by our community](https://docs.photoprism.app/developer-guide/translations-weblate/), and fixes for recently discovered issues.
What's new?
- UX: [Search toolbars and tabs remain visible while scrolling](https://github.com/photoprism/photoprism/issues/4830)
- UX: [Users can choose their Start Page and Time Zone in Settings](https://github.com/photoprism/photoprism/issues/577)
- UX: [Disk usage can be limited and displayed in sidebar navigation](https://github.com/photoprism/photoprism/issues/4266)
- UX: [Metadata displayed in the Cards View can be configured](https://github.com/photoprism/photoprism/issues/1164)
- UX: [Improved List View layout for easier selection](https://github.com/photoprism/photoprism/issues/4727)
- Index: [Added file format support for Adobe PDF documents](https://github.com/photoprism/photoprism/issues/4600)
- Albums: [Added file name and file type settings for zip downloads](https://github.com/photoprism/photoprism/issues/4344)
- Albums: [Added default sort order settings for each album type](https://github.com/photoprism/photoprism/issues/405)
- Videos: [Added codec search filter and Nvidia GPU detection](https://github.com/photoprism/photoprism/issues/4848)
- Labels: [Fixed searching for labels that consist only of emojis](https://github.com/photoprism/photoprism/issues/4761)
- Upload: [Fixed an issue that could cause the same album to be created multiple times](https://github.com/photoprism/photoprism/discussions/4849)
- WebDAV: [File downloads are flagged as failed when retry limit is reached](https://github.com/photoprism/photoprism/issues/4827)
- MariaDB: [Added version check to determine zero-configuration SSL support](https://github.com/photoprism/photoprism/issues/4837)
- Translations: [Updated Chinese (Simplified), French, German, Turkish, and Ukrainian](https://docs.photoprism.app/developer-guide/translations-weblate/)
- Security: Go has been updated to v1.24.1, which includes fixes and improvements
### Build 1.2502.28 (February 28, 2025)
With [this update](https://github.com/photoprism/photoprism/releases/tag/250228-43447fa38), you will get additional usability and performance improvements, as well as a new thumbnail size for [Retina 5K displays](https://github.com/photoprism/photoprism/issues/4810) that bridges the gap [between 4K and 8K](https://docs.photoprism.app/user-guide/settings/advanced/#which-thumbnails-will-be-generated).
What's new?
- UX: [Added menu action button for archiving pictures from albums](https://github.com/photoprism/photoprism/issues/3442)
- UX: [Upload to WebDAV menu action only appears if sharing is enabled](https://github.com/photoprism/photoprism/commit/cb9826de96497d8ef052dcfd905cf3a5e34b84f1)
- Viewer: [Content preloading is less eager to reduce server load](https://github.com/photoprism/photoprism/commit/69290b1ab17471d6dbed1ad5cb382cd212ad9799)
- Viewer: [Fullscreen toggle is always visible in experimental mode](https://github.com/photoprism/photoprism/commit/bc9c1205ee379b95751c4791e63b2850b96c42b5)
- Viewer: [Added a new thumbnail size suitable for Retina 5K displays](https://github.com/photoprism/photoprism/issues/4810)
- Videos: [M4V container files are assumed to be MP4 compatible](https://github.com/photoprism/photoprism/issues/4820)
- Places: [Browser scrollbar stays hidden when cluster view is open](https://github.com/photoprism/photoprism/commit/1b0c3c804ef51ed42bed9cbd52df61f1f1265102)
### Build 1.2502.24 (February 24, 2025)
This [major new release](https://github.com/photoprism/photoprism/releases/tag/250223-b79d21907) features an [updated user interface](https://github.com/photoprism/photoprism/issues/3168#screenshots) with many usability enhancements and new features, such as a [hybrid photo and video viewer](https://github.com/photoprism/photoprism/issues/1307) that replaces the [dedicated video player](https://github.com/photoprism/photoprism/issues/3372), a [redesigned edit dialog](https://github.com/photoprism/photoprism/issues/4763) that is more responsive and easier to use, and an immersive [3D Earth](https://github.com/photoprism/photoprism/issues/4762) view in [Places](https://demo.photoprism.app/library/places). It also includes dozens of layout optimizations for right-to-left languages.
Breaking Changes
- It is recommended that you [perform a complete rescan of your library](https://docs.photoprism.app/user-guide/library/originals/#indexing-your-originals) after upgrading, as otherwise videos that do not require transcoding may be [transcoded during playback](https://docs.photoprism.app/user-guide/organize/video/#transcoding) due to missing metadata, resulting in high CPU and disk usage. [Learn more ›](https://docs.photoprism.app/user-guide/library/originals/#indexing-your-originals)
- If you are using a [custom user interface theme](/pro/kb/customization/), the color names and variables required for it have changed and must be updated to be compatible with this and future releases. You are welcome to contact our support team if you have questions regarding theme customization. [Learn more ›](/pro/kb/customization/)
What's new?
- UX: [Updated user interface with many new features and enhancements](https://github.com/photoprism/photoprism/issues/3168#screenshots)
- UX: [Edit dialog has been redesigned to be more mobile and user-friendly](https://github.com/photoprism/photoprism/issues/4763)
- UX: [New hybrid photo and video viewer replaces dedicated video player](https://github.com/photoprism/photoprism/issues/1307)
- Viewer: [Higher resolution thumbnails are used when zooming into an image](https://github.com/photoprism/photoprism/issues/4704)
- Viewer: [Videos are played automatically when a slideshow is running](https://github.com/photoprism/photoprism/issues/4698)
- Search: [Cards view and mosaic view show the video duration on thumbnails](https://github.com/photoprism/photoprism/issues/3168#screenshots)
- Search: [Cards view always shows the filename and camera details for videos](https://github.com/photoprism/photoprism/issues/3168#screenshots)
- Places: [Added a 3D Earth view mode that can be enabled for any map](https://github.com/photoprism/photoprism/issues/4762)
- Places: [Upgraded MapLibre GL JS library from v3.6 to v5.1](https://github.com/photoprism/photoprism/issues/4058) by [@QyuBee](https://github.com/QyuBee)
- Places: [Locations are no longer estimated for non-photographic pictures](https://github.com/photoprism/photoprism/issues/4589)
- Places: [Updated reverse geocoding data to include corrections from OSM](https://github.com/photoprism/photoprism/issues/4688)
- Metadata: [Labels are set based on matching keywords in title, subject](https://github.com/photoprism/photoprism/issues/4602) and [caption](https://github.com/photoprism/photoprism/issues/4603)
- Metadata: [Improved recognition of images created by digital film scanners](https://github.com/photoprism/photoprism/issues/4581)
- Metadata: [Numerals are preserved in titles generated from file and folder names](https://github.com/photoprism/photoprism/issues/3447)
- Import: [Advanced users can configure a custom destination file path pattern](https://docs.photoprism.app/user-guide/library/import/#changing-the-import-file-path)
- Settings: [Fixed Windows resource string in WebDAV dialog when using HTTPS](https://github.com/photoprism/photoprism/issues/4798)
- API: [`Description` field has been renamed to `Caption` in `/photos` endpoints](https://github.com/photoprism/photoprism/issues/4603#issuecomment-2631743288)
- CLI: [Added a `users` command flag to find and restore deleted user accounts](https://github.com/photoprism/photoprism/issues/4570)
- Setup: [Renamed `docker-compose.yml` config examples to `compose.yaml`](https://github.com/photoprism/photoprism/issues/4591)
- Config: [Added options to recreate Unix server socket and set permissions](https://github.com/photoprism/photoprism/issues/4765)
- Docker: [Replaced entrypoint script for graceful server shutdown and restart](https://github.com/photoprism/photoprism/issues/4767)
- Docker: [Base image has been upgraded from Ubuntu 24.04 to 24.10 (Oracular Oriole)](https://github.com/photoprism/photoprism/issues/4631)
- Docker: [NAS devices running a very old Linux kernel can use the `:legacy` image](https://github.com/photoprism/photoprism/issues/4339#issuecomment-2673765576)
- Security: [Added `X-Robots-Tag` header and `robots.txt` file to control crawlers](https://github.com/photoprism/photoprism/issues/4574)
- Security: Go has been upgraded to v1.24, which includes fixes and improvements
### Build 1.2409.15 (September 15, 2024)
This update includes [improved HEIC file support for iOS 18 compatibility](https://github.com/photoprism/photoprism/issues/4439), updated dependencies and [translations](https://docs.photoprism.app/developer-guide/translations-weblate/), UX enhancements, and fixes for recently discovered issues. Please note that a [complete re-scan of your library](https://docs.photoprism.app/user-guide/library/originals/) is required to increase the [GPS location accuracy](https://github.com/photoprism/photoprism/issues/3953#issuecomment-2351563642) of pictures, e.g. under [Places](https://docs.photoprism.app/user-guide/organize/places/).
What's new?
- HEIC: [Improved `.heic` image file support for compatibility with iOS 18](https://github.com/photoprism/photoprism/issues/4439)
- Search: [Sidecar files are no longer shown in the results when sorting by file size](https://github.com/photoprism/photoprism/issues/4519)
- Archive: [Recently archived pictures are displayed first by default](https://github.com/photoprism/photoprism/issues/3975)
- Places: [Fixed an issue where no pictures were found when clicking on clusters](https://github.com/photoprism/photoprism/issues/3953)
- Library: [Removed the archive button from the action menu under](https://github.com/photoprism/photoprism/issues/4255) [*Library > Hidden*](https://demo.photoprism.app/library/hidden)
- API: [Fixed an issue where update requests could fail silently in case of database errors](https://github.com/photoprism/photoprism/issues/4504)
- API: [Added interactive Swagger developer documentation with examples](https://docs.photoprism.app/developer-guide/api/docs/)
- Security: Go has been updated to v1.22.7, which includes security and bug fixes
- Translations: [Added Irish (Gaeilge) and updated Basque, French and German](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2407.11 (July 11, 2024)
This release adds support for [single sign-on via OpenID Connect (OIDC)](https://www.photoprism.app/pro/kb/openid-connect/) and includes the [latest translations](https://docs.photoprism.app/developer-guide/translations-weblate/) as well as fixes for recently discovered issues.
What's new?
- Auth: [Added support for single sign-on via OpenID Connect (OIDC)](/pro/kb/openid-connect/)
- Index: [Slashes and null bytes are trimmed from `.ppignore` patterns](https://github.com/photoprism/photoprism/discussions/4349#discussioncomment-9848756)
- Videos: [Added support for MPEG-5 Essential Video Coding (EVC)](https://github.com/photoprism/photoprism/issues/4314)
- Videos: [Added filter to transcode 10bit videos with Intel QSV](https://github.com/photoprism/photoprism/issues/4380)
- CLI: [Local passwords can be removed with `photoprism passwd --rm`](/pro/kb/roles/)
- Security: Go has been updated to the latest stable release v1.22.5
- Translations: [Updated French and Japanese](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2405.31 (May 31, 2024)
With this update, you can choose to install FFmpeg 7 for faster [software video transcoding](https://docs.photoprism.app/getting-started/advanced/transcoding/#software-transcoding). You also get the latest translations [contributed by our community](https://docs.photoprism.app/developer-guide/translations-weblate/) as well as improved [backup commands](https://docs.photoprism.app/user-guide/backups/) and [configuration defaults](https://docs.photoprism.app/getting-started/config-options/).
What's new?
- Videos: [You can choose to install FFmpeg 7.0 for faster transcoding](https://docs.photoprism.app/getting-started/advanced/transcoding/#software-transcoding)
- MariaDB: [Backup and restore commands support socket connections](https://github.com/photoprism/photoprism/issues/4306)
- Config: [Increased auto-index delay and disabled auto-import by default](https://github.com/photoprism/photoprism/issues/4310)
- Translations: [Updated Japanese](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2405.28 (May 28, 2024)
This service release reduces the server load when [downloading many files](https://github.com/photoprism/photoprism/issues/4298), expands the list of [available config options](https://docs.photoprism.app/getting-started/config-options/), and gets you the latest translations [contributed by our community](https://docs.photoprism.app/developer-guide/translations-weblate/).
What's new?
- Download: [Zip archives are not compressed to reduce server load](https://github.com/photoprism/photoprism/issues/4298)
- Search: [Added `added`, `updated` and `edited` search filters for app developers](https://github.com/photoprism/photoprism/issues/4300)
- Config: [Replaced the terms whitelist and blacklist with alternatives](https://github.com/photoprism/photoprism/issues/3981)
- Config: [New feature flag `PHOTOPRISM_DISABLE_BACKUPS` disables all backups](https://github.com/photoprism/photoprism/issues/4294)
- Config: [New feature flag `PHOTOPRISM_DISABLE_VIPS` disables the use of libvips](https://github.com/photoprism/photoprism/issues/4296)
- Translations: [Updated French and German](https://docs.photoprism.app/developer-guide/translations-weblate/)
### Build 1.2405.23 (May 23, 2024)
This update adds a scheduler so you can [easily create database backups](/pro/kb/config-options/#backup) and [re-index your library](/pro/kb/config-options/#indexing) at regular intervals. It also includes [many updated dependencies](https://github.com/photoprism/photoprism/issues/4084#issuecomment-2112733848) and [support for ICC color profiles](/pro/kb/config-options/#preview-images), which especially benefits Apple iPhone and professional users working with color spaces other than sRGB. 🎨
Breaking Changes
- Starting with this release, an [activation of your license](/pro/kb/activation/#step-3) under *Settings > Upgrade* is required. This is necessary in order for us to publicly distribute the Docker image, making it easier to install. Our [Knowledge Base](/pro/kb/activation/#step-3) explains how you can [activate your instances](/pro/kb/activation/#step-3) if you have not already done so.
- If you keep the [default settings](/pro/kb/config-options/#backup), daily database backups will be automatically created, with up to 3 backup files being retained. This is to prevent the available storage space from filling up. We recommend [setting the corresponding config options](/pro/kb/config-options/#backup) before installing the update if you want to disable scheduled backups, keep more backup files, or prefer a specific time for creating backups. The previously available `--disable-backups` flag has been deprecated in favor of [these finer-grained options](/pro/kb/config-options/#backup).
- In order to preserve ICC color profiles and reduce memory usage, new thumbnails will be [generated with the `libvips` image processing library](https://github.com/photoprism/photoprism/issues/1474). You can run the `photoprism thumbs -f` [command in a terminal](/pro/kb/cli/) to regenerate your existing thumbs as needed, or delete the `storage/cache/thumbnails` folder and then re-index your library. To continue using the native image processing library, set `PHOTOPRISM_THUMB_LIBRARY` to `"imaging"` in your `compose.yaml` or `docker-compose.yml` [configuration file](/pro/kb/config-options/#preview-images). Note that if you [build from source](https://docs.photoprism.app/getting-started/faq/#building-from-source), the system on which you build and/or run PhotoPrism Pro must have `libvips` >= 8.10 installed.
What's new?
- Colors: [Added libvips support to preserve ICC profiles in thumbnails](https://github.com/photoprism/photoprism/issues/1474)
- Search: [Clicking on a timestamp finds pictures taken on the same day](https://github.com/photoprism/photoprism/issues/4273)
- Search: [Added a sort option to order search results by picture title](https://github.com/photoprism/photoprism/pull/4218)
- Review: [Photos are automatically approved when adding them to an album](https://github.com/photoprism/photoprism/issues/4229)
- People: [Faces tagged on private or archived pictures will be ignored](https://github.com/photoprism/photoprism/issues/4238)
- Index: [`*.thm` thumbnail files are not used as primary image anymore](https://github.com/photoprism/photoprism/issues/3900)
- Index: [Added a config option for scheduling automatic library rescans](https://github.com/photoprism/photoprism/issues/4251)
- Index: [Improved recovery of metadata from sidecar YAML files](https://github.com/photoprism/photoprism/issues/4286)
- Upload: [Improved ETA display when using the web upload dialog](https://github.com/photoprism/photoprism/issues/4285)
- Backups: [Added config options for creating backups at regular intervals](https://github.com/photoprism/photoprism/issues/4243)
- Moments: [Background worker no longer creates backups to avoid disk activity](https://github.com/photoprism/photoprism/issues/4237)
- Docker: [Upgraded base image from Ubuntu 23.10 to Ubuntu 24.04 LTS](https://github.com/photoprism/photoprism/issues/4084)
- Security: Go has been updated to the latest stable release v1.22.3
- Translations: [Updated Chinese (traditional), Danish, French, and German](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2404.20 (April 20, 2024)
Our new stable release comes with a long list of indexing and security-related improvements. Most notably, we've added support for [2-Factor Authentication (2FA)](https://docs.photoprism.app/user-guide/users/2fa/) to protect your account in case someone gains access to your password.
What's new?
- Account: [Added support for 2-Factor Authentication (2FA)](https://github.com/photoprism/photoprism/issues/808)
- Account: [Added dialog to manage App Passwords from the UI](https://github.com/photoprism/photoprism/issues/4114)
- Places: [Updated reverse geocoding data and standard map tiles](https://github.com/photoprism/photoprism/issues/3849)
- Albums: [Fixed links to albums in the settings tab of the edit dialog](https://github.com/photoprism/photoprism/issues/4060)
- Photos: [Non-JPEG files like HEIC are no longer flagged as stacks in the UI](https://github.com/photoprism/photoprism/issues/3993)
- Videos: [Improved Intel QSV hardware transcoding support and performance](https://github.com/photoprism/photoprism/issues/4030)
- UI/UX: [Improved visibility of buttons and toggles in search results](https://github.com/photoprism/photoprism/issues/4174)
- Index: [A warning is shown for files with an invalid filename extension](https://github.com/photoprism/photoprism/issues/3518)
- Index: [Nested storage folders within the originals path are ignored](https://github.com/photoprism/photoprism/issues/1642)
- Import: [Modification times are preserved when moving or copying files](https://github.com/photoprism/photoprism/issues/4139)
- Metadata: [Media files with a matching `ContentIdentifier` can be stacked](https://github.com/photoprism/photoprism/issues/3960)
- Metadata: [File mod time instead of birth time is used as creation time fallback](https://github.com/photoprism/photoprism/issues/4157)
- Metadata: [Improved validation for focal length, f-number, and exposure values](https://github.com/photoprism/photoprism/issues/4170)
- Metadata: [Stop words are no longer ignored when generating titles from filenames](https://github.com/photoprism/photoprism/issues/4192)
- WebDAV: [File modification date is preserved if client submits an `X-OC-MTime` header](https://github.com/photoprism/photoprism/issues/3959)
- API: [Added support for OAuth2 Client Credentials and Access Tokens](https://github.com/photoprism/photoprism/issues/3943)
- API: [Added Prometheus-compatible metrics and monitoring endpoint](https://github.com/photoprism/photoprism/issues/213)
- CDN: [Improved Cross-Origin Resource Sharing (CORS) and cache headers](https://github.com/photoprism/photoprism/issues/3931)
- MariaDB: [Info log is shown when waiting for the database to become available](https://github.com/photoprism/photoprism/issues/4059)
- MariaDB: [Changed image name in Docker Compose config example for ARMv7](https://github.com/photoprism/photoprism/pull/4199)
- Docker: [Missing user accounts are automatically created by the entrypoint script](https://github.com/photoprism/photoprism/issues/4000)
- Setup: [Added ARMv7 `tar.gz` packages for installation without Docker](https://github.com/photoprism/photoprism/issues/4082)
- Performance: [Added index for `files.file_error` to reduce query time](https://github.com/photoprism/photoprism/issues/4149)
- Security: Go has been updated to the latest stable release v1.22.2
### Build 1.2312.19 (December 19, 2023)
This update provides you with the latest dependencies and adds support for the Material Exchange Format (MXF).
What's new?
- Videos: [Added support for Material Exchange Format (MXF) files](https://github.com/photoprism/photoprism/issues/3935)
- Security: Go has been updated to the latest stable release v1.21.5
### Build 1.2311.28 (November 28, 2023)
This service release includes updated dependencies and fixes for recently discovered issues.
What's new?
- Search: [Improved camera and lens information in the cards view details](https://github.com/photoprism/photoprism/issues/3816)
- Search: [Fixed cards view rendering when a lens has no model description](https://github.com/photoprism/photoprism/issues/3918)
- Search: [Added filter to find pictures by resolution range in Megapixels (MP)](https://github.com/photoprism/photoprism/issues/3896)
- PWA: [Fixed list of available icon sizes in the app manifest file](https://github.com/photoprism/photoprism/pull/3838)
- JPEG: [Fixed regression when handling image files with EOF error](https://github.com/photoprism/photoprism/issues/3855)
- JPEG: [Fixed indexing of image files with invalid color metadata](https://github.com/photoprism/photoprism/issues/3843)
- JPEG/PNG: [Added panic handler for unexpected thumbnail save errors](https://github.com/photoprism/photoprism/issues/3858)
- HEIC: [Libheif has been upgraded from version 1.13.0 to 1.17.1](https://github.com/photoprism/photoprism/issues/3852)
- RAW: [Darktable has been upgraded from version 4.2.1 to 4.4.2](https://github.com/photoprism/photoprism/issues/3741)
- Videos: [Improved performance when extracting still images for creating thumbnails](https://github.com/photoprism/photoprism/pull/3893)
- Vectors: [Improved SVG conversion using RSVG instead of ImageMagick](https://github.com/photoprism/photoprism/issues/3885)
- Docker: [Base image has been upgraded from Ubuntu 23.04 to 23.10 (Mantic Minotaur)](https://github.com/photoprism/photoprism/blob/develop/docker/develop/mantic/Dockerfile)
- Security: Go has been updated to the latest stable release v1.21.4
### Build 1.2310.21 (October 21, 2023)
This update adds search filters for finding pictures by ISO number, focal length, aperture, and altitude. It also includes a number of user interface improvements, updated translations, as well as fixes for recently discovered issues.
What's new?
- Search: [Added filters for ISO number, focal length, and aperture range](https://github.com/photoprism/photoprism/issues/3818)
- Search: [Added `alt:...` filter to find pictures by altitude range](https://github.com/photoprism/photoprism/pull/3800)
- Search: [Cards view shows ISO number, focal length, aperture, and exposure](https://github.com/photoprism/photoprism/issues/3816)
- Live Photos: [Fixed Google HEVC motion photo playback and transcoding](https://github.com/photoprism/photoprism/issues/3814)
- Live Photos: [Improved indexing of related files with vendor-specific naming schemes](https://github.com/photoprism/photoprism/issues/2983)
- Metadata: [Updated offline map data for more accurate timezone lookups](https://github.com/photoprism/go-tz)
- Metadata: [Creation time is calculated with UTC offset if timezone is unknown](https://github.com/photoprism/photoprism/discussions/3780)
- Config: [Creation of default certificate is skipped if HTTPS/TLS is disabled](https://github.com/photoprism/photoprism/issues/3823)
- Translations: [Updated German, Greek, and Romanian](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2310.11 (October 11, 2023)
This service release includes a number of usability improvements requested by our users as well as fixes for recently discovered issues.
What's new?
- PWA: [Fixed automatic screen orientation in Google Chrome on Android](https://github.com/photoprism/photoprism/issues/3413)
- Upload: [Current album is preselected when using the mobile nav menu](https://github.com/photoprism/photoprism/issues/3784)
- Videos: [Creation of thumbnails can only be disabled in experimental mode](https://github.com/photoprism/photoprism/issues/3793)
- Settings: [Ability to permanently delete files is now enabled by default](https://github.com/photoprism/photoprism/issues/3801)
- RAW/HEIC: [Original media information is shown in the cards view details](https://github.com/photoprism/photoprism/issues/2040)
- Live Photos: [Embedded video files can be streamed and transcoded](https://github.com/photoprism/photoprism/issues/3764)
- Metadata: [Improved camera make and model name normalization](https://github.com/photoprism/photoprism/discussions/3077)
- Security: Go has been updated to the latest stable release v1.21.3
### Build 1.2309.23 (September 23, 2023)
This major update includes a [redesigned Places view](https://user-images.githubusercontent.com/301686/269433540-cd48e79f-b2a8-4fb5-bc54-52467b15b743.jpg), with the search box moved to the top and a preview for selected clusters at the bottom. We've also added support for [Samsung](https://github.com/photoprism/photoprism/issues/439)/[Google Motion Photos](https://github.com/photoprism/photoprism/issues/1739), so you can view them like Apple Live Photos after [re-indexing your library](https://docs.photoprism.app/user-guide/library/originals/). Beyond those highlights, you'll get many usability improvements, new search filters, and fixes for recently discovered issues.
What's new?
- UX: [Added a preview image to the Labels tab in the photo edit dialog](https://github.com/photoprism/photoprism/pull/3532)
- UX: [Reduced padding in mosaic view in favor of larger thumbnails](https://github.com/photoprism/photoprism/issues/3572)
- UX: [Edit dialog allows pasting latitude and longitude in a single operation](https://github.com/photoprism/photoprism/pull/3568)
- UX: [Reduced the number of info notifications in the user interface](https://github.com/photoprism/photoprism/issues/3608)
- UX: [Improved user interface styles, added new "Chrome" and "Mint" themes](https://github.com/photoprism/photoprism/commit/20df14e9d16b456a5edbc456544f875ee9da16a4)
- Search: [Added `scan:false` filter to find photos that are not scans](https://github.com/photoprism/photoprism/commit/be0fdc1774266bd4ec09e01ab93496fb07a4cbed)
- Search: [Added `favorite:false` filter to find pictures not marked as favorites](https://github.com/photoprism/photoprism/commit/20d20c7fa923baa9b5041631b3bcf6873bc2c874)
- Albums: [New share preview shows album contents as a stack of Polaroids](https://github.com/photoprism/photoprism/issues/3658#issuecomment-1711870557)
- Albums: [Fixed preview image URL when sharing album links](https://github.com/photoprism/photoprism/issues/3658)
- Albums: [Current album is preselected when opening the upload dialog](https://github.com/photoprism/photoprism/issues/3644)
- Albums: [Last edited timestamp is updated when pictures are added](https://github.com/photoprism/photoprism/issues/3080)
- People: [Fixed an error when reusing the name of a previously deleted person](https://github.com/photoprism/photoprism/issues/3414)
- Places: [Added cluster view to browse pictures close to each other in an overlay](https://github.com/photoprism/photoprism/issues/1187)
- Places: [Added support sub-km distances when searching for locations](https://github.com/photoprism/photoprism/issues/3558)
- Places: [Added support for the `label` and `category` search filters](https://github.com/photoprism/photoprism/commit/a865300666bfa26f8de47ac3fb19a31617f97056)
- Places: [Added map style selector and a scale for comparing distances](https://github.com/photoprism/photoprism/issues/2106)
- Archive: [Added "Delete All" button to permanently delete all archived files](https://github.com/photoprism/photoprism/issues/3701)
- Library: [Added option for admins to perform index and cache cleanup from the UI](https://github.com/photoprism/photoprism/issues/3699)
- Library: [Fixed escaping of hash characters in folder names](https://github.com/photoprism/photoprism/issues/3695)
- Live Photos: [Added support for Samsung Motion Photos](https://github.com/photoprism/photoprism/issues/439)
- Live Photos: [Added support for Google Camera Motion Photos](https://github.com/photoprism/photoprism/issues/1739)
- Live Photos: [Fixed indexing of sidecar video file properties](https://github.com/photoprism/photoprism/issues/3559)
- Videos: [Added support for AMD GPUs in `install-gpu.sh` script](https://github.com/photoprism/photoprism/pull/3710)
- Videos: [Removed deprecated FFmpeg `-vsync vfr` command flag](https://github.com/photoprism/photoprism/issues/3659#issuecomment-1707529050)
- Metadata: [Changed order of field names from which the title is extracted](https://github.com/photoprism/photoprism/commit/82dac4b7db65f1e490d3cd26a17b122832b0445f)
- Metadata: [Added support for reading fstop favorite flag from XMP sidecar files](https://github.com/photoprism/photoprism/pull/1873)
- Metadata: [Samsung/Google Motion Photos are flagged as Live Photos](https://github.com/photoprism/photoprism/issues/2788)
- Config: [Added support for serving HTTP requests over Unix sockets](https://github.com/photoprism/photoprism/issues/2337)
- Config: [A lower cache duration can be set for video content](https://github.com/photoprism/photoprism/issues/3631)
- SQLite: [Updates are performed in batches to limit the number of variables](https://github.com/photoprism/photoprism/issues/3742)
- Docker: [Added support for user ID ranges 1201-1250 and 2000-2100](https://github.com/photoprism/photoprism/issues/3719)
- Security: [Reduced bcrypt cost for faster login on small devices](https://github.com/photoprism/photoprism/issues/3718)
- Security: Go has been updated to the latest stable release v1.21.1
- Translations: [Updated Chinese (Simplified and Traditional)](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2307.21 (July 21, 2023)
With this update, you get the latest features and enhancements contributed by our community, a number of security improvements, as well as fixes for recently discovered issues.
What's new?
- UX: [A preview image has been added to the Labels tab in the photo edit dialog](https://github.com/photoprism/photoprism/pull/3532)
- Themes: [Added "Mint" and improved the default theme styles](https://github.com/photoprism/photoprism/commit/20df14e9d16b456a5edbc456544f875ee9da16a4)
- Search: [Added `geo:false` filter to find pictures without GPS coordinates](https://github.com/photoprism/photoprism/issues/3493)
- Photos: [JPEG files with missing EOI marker are automatically repaired](https://github.com/photoprism/photoprism/pull/2721)
- Photos: [Fixed an error when opening panoramas taken with a Samsung S21](https://github.com/photoprism/photoprism/issues/3363)
- Videos: [Added a config option to limit the resolution of transcoded videos](https://github.com/photoprism/photoprism/issues/3466)
- Videos: [Fixed container and codec checks in `photoprism convert` command](https://github.com/photoprism/photoprism/issues/3525)
- Metadata: [Dates in WhatsApp generated file names can be parsed](https://github.com/photoprism/photoprism/issues/1102)
- Metadata: [Year 0000 is mapped to 0001 when parsing dates from Exiftool](https://github.com/photoprism/photoprism/pull/2508)
- Security: [Clipboard contents are cleared on logout and when user privileges change](https://github.com/photoprism/photoprism/issues/3512)
- Security: Go has been updated to v1.20.6, which includes bug fixes and enhancements
- Translations: [Updated Japanese](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2306.25 (June 25, 2023)
This service release includes the [latest translations contributed by our community](https://translate.photoprism.app/engage/photoprism/), as well as fixes for recently discovered issues.
What's new?
- Albums: [Invalid entries are automatically hidden and flagged as missing](https://github.com/photoprism/photoprism/issues/3481)
- CLI: [Fixed an issue where entering a very long password could disable the login](https://github.com/photoprism/photoprism/issues/3482)
- Security: [Updated third-party dependencies in backend](https://github.com/photoprism/photoprism/commit/96e0981c3179a428ea4c5614ee3ffec417232d52) [and frontend](https://github.com/photoprism/photoprism/commit/ee6e6c66e388ddb901e212dc6736f5dbfa28c459)
- Translations: [Updated Chinese (Simplified), Italian, and Japanese](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2306.15 (June 15, 2023)
This update includes new features and enhancements contributed [by our community](https://docs.photoprism.app/developer-guide/pull-requests/), as well as fixes for recently discovered issues.
What's new?
- Photos: [Related albums are displayed in the Info tab of the edit dialog](https://github.com/photoprism/photoprism/pull/3095)
- Photos: [Added a link from the Files tab to the related folder in the file browser](https://github.com/photoprism/photoprism/pull/2926)
- Moments: [Added labels to match *Holidays* as well as additional *Pets*](https://github.com/photoprism/photoprism/pull/3081)
- CLI: [Added `photoprism find` command to search the index for specific files](https://github.com/photoprism/photoprism/pull/3222)
- CLI: [Fixed the `photoprism import` command destination parameter type](https://github.com/photoprism/photoprism/issues/3473)
- Security: [Updated third-party dependencies in backend](https://github.com/photoprism/photoprism/commit/b91723e90caf3012cf55a4d2b2f68dda81c9f702) [and frontend](https://github.com/photoprism/photoprism/commit/9a5af3176e937a494d69f96e99d9191e0f1b5ee2)
### Build 1.2306.09 (June 9, 2023)
With this update, you get a new high-resolution vector world map as well as a special terrain mode for Places that allows you to view the "Satellite", "Outdoor" and "Topography" maps in 3D. It also includes fixes for recently discovered issues and improves compatibility with the upcoming [MariaDB v11.0](https://mariadb.com/kb/en/release-notes-mariadb-11-0-series/).
If you are upgrading from MariaDB 10.x to 11.0, please [make sure that you replace](https://github.com/photoprism/photoprism/commit/bff649469d084498a1e75492c0bd99bda3f5a340#diff-03a31d6e73f48b7bba98b65352ce67a7d153fe2461f9c7b5e76be49a97ebf0cb) `command: mysqld` with `command: ` (followed by the command flags) in your `compose.yaml` or `docker-compose.yml` file, otherwise the database server might fail to start.
What's new?
- Places: [Improved the level of detail of the freely available default world map](https://github.com/photoprism/photoprism/issues/2998#issuecomment-1575607476)
- Places: [Added terrain mode to display the satellite, outdoor and topography maps in 3D](https://github.com/photoprism/photoprism/issues/3455)
- Folders: [Searching for substrings now returns all matching albums](https://github.com/photoprism/photoprism/issues/3441)
- Search: [Fixed an issue where the "Unknown country" filter has been ignored](https://github.com/photoprism/photoprism/issues/3412)
- Navigation: [Fixed account feature check when clicking on the profile picture](https://github.com/photoprism/photoprism/pull/3365)
- MariaDB: [Improved compatibility with the upcoming release 11.0](https://github.com/photoprism/photoprism/issues/3443)
- Config: [CSP header is updated automatically when a CDN is configured](https://github.com/photoprism/photoprism/issues/3454)
- Security: [Malicious client requests can be automatically detected and blocked](https://docs.photoprism.app/getting-started/config-options/#web-server)
- Security: [Updated third-party dependencies in backend and frontend](https://github.com/photoprism/photoprism/commit/0ff2fee91d791f203a3c64bc0409746cd8a62a47)
- Security: Go has been updated to v1.20.5, which includes bug fixes and enhancements
- Translations: [Updated Chinese (Traditional), Chinese (Simplified), Dutch, German, French, Italian, and Slovak](https://translate.photoprism.app/engage/photoprism/)
### Build 1.2305.06 (May 6, 2023)
This update resolves two recently reported issues and includes updated translations.
What's new?
- Sharing: [Upload checks if files have been deleted](https://github.com/photoprism/photoprism/issues/3379)
- CLI: [Logging output is reduced in production mode](https://github.com/photoprism/photoprism/issues/3370)
- Translations: [Updated French](https://github.com/photoprism/photoprism/pull/3373)
### Build 1.2305.04 (May 4, 2023)
- RAW: [Upgraded RawTherapee from v5.8 to v.5.9 to fix ProRAW support](https://github.com/photoprism/photoprism/issues/2291)
- Metadata: [Notes can be extracted from the Comment and UserComment fields](https://github.com/photoprism/photoprism/issues/3352)
- Settings: [Changed the order in theme dropdown so that Community Edition themes come first](https://github.com/photoprism/photoprism/issues/3368)
- Docker: [Ubuntu base image has been upgraded from v22.04 to v23.04](https://github.com/photoprism/photoprism/issues/3305)
### Build 1.2304.17 (April 17, 2023)
- Albums: [Improved error handling and validation of query parameters](https://github.com/photoprism/photoprism/issues/3320)
- Albums: ["Download as zip" button is displayed on mobile screens](https://github.com/photoprism/photoprism/issues/3340)
- Videos: [Improved detection of HEVC support for Google Chrome](https://github.com/photoprism/photoprism/issues/3275)
- Metadata: [Added TakenAtLocal to YAML backups to prevent incorrectly restored times](https://github.com/photoprism/photoprism/issues/3338)
- WebDAV: [Enabled access to the originals and import folders in read-only mode](https://github.com/photoprism/photoprism/issues/3183)
- WebDAV: [Replaced client library to prevent incomplete uploads to other servers](https://github.com/photoprism/photoprism/issues/3310)
- WebDAV: [Download sync is prevented when read-only mode is enabled](https://github.com/photoprism/photoprism/commit/d48db6cae4b25e8ff3daf867db42e106ea4c2297)
- Backups: [Improved backup and restore commands to better handle large index dumps](https://github.com/photoprism/photoprism/issues/3140)
- Config: [Added advanced HTTP cache control options](https://github.com/photoprism/photoprism/issues/3297)
- Config: [Added option to stream videos over a Content Delivery Network (CDN)](https://github.com/photoprism/photoprism/issues/2875)
- Docker: [MariaDB image and binaries have been upgraded from v10.9 to v10.11](https://github.com/photoprism/photoprism/issues/3332)
- Security: [Improved bcrypt password support with explicit 72-character limit](https://github.com/photoprism/photoprism/issues/1987#issuecomment-1507190623)
- Security: Go has been upgraded to v1.20.3, which includes bug fixes and improvements
- Translations: [Added Basque](https://github.com/photoprism/photoprism/pull/3323/files) (Euskara)
### Build 1.2303.15 (March 15, 2023)
- Auth: [Admins can manage user accounts and active sessions through the web UI](https://www.photoprism.app/pro/kb/roles/)
- Auth: [Uploader user role has been renamed to Contributor](https://www.photoprism.app/pro/kb/roles/)
- People: [Entering names is faster with many faces tagged](https://github.com/photoprism/photoprism/issues/3151)
- Videos: [Specific video and audio streams can be selected for transcoding](https://github.com/photoprism/photoprism/issues/3284)
- Moments: [Changed default sort order in the overview to "newest"](https://github.com/photoprism/photoprism/issues/3280)
- Download: [Added settings to choose which files to download by default](https://github.com/photoprism/photoprism/issues/449)
- Security: Go has been upgraded to v1.20.2, which includes bug fixes and improvements
### Build 1.2302.24 (February 24, 2023)
- Metadata: [Date defaults caused by software or camera bugs are ignored](https://github.com/photoprism/photoprism/issues/3229)
- Metadata: [Scanned images are automatically recognized by device name](https://github.com/photoprism/photoprism/issues/3221)
- Videos: [Added .dv to the list of known video file types](https://github.com/photoprism/photoprism/issues/3226)
- Videos: [Playback durations of less than one second can be indexed and displayed](https://github.com/photoprism/photoprism/issues/3224)
- Index: [Improved performance by skipping updates when there are no changes](https://github.com/photoprism/photoprism/issues/3227)
- WebDAV: [Updated studio-b12/gowebdav client library](https://github.com/photoprism/photoprism/issues/2267)
### Build 1.2302.21 (February 21, 2023)
- UX: [Improved theme styles and search field contrast in Places](https://github.com/photoprism/photoprism/commit/0d2a25eb0cd12e114dff87570e4015b6eba8c73c)
- People: [Ambiguous faces are skipped when matching to improve performance](https://github.com/photoprism/photoprism/issues/3124)
- Search: [Sepia colored pictures are excluded when using the `mono` filter](https://github.com/photoprism/photoprism/issues/2657)
- Metadata: [Software name is displayed on the Files tab, if available](https://github.com/photoprism/photoprism/commit/3c1b7acf1191c48620e3bdc8256694b7513856c9)
- Metadata: [Valid year range in Exif data and filenames has been extended from 1990 to 1970](https://github.com/photoprism/photoprism/issues/3220)
- Index: [Corrupted JPEG images are automatically repaired if necessary](https://github.com/photoprism/photoprism/issues/2463)
- Index: [TIFF images with unsupported file format features can be converted](https://github.com/photoprism/photoprism/issues/1612)
- Config: [Migrations are skipped if the same version has already been initialized](https://github.com/photoprism/photoprism/issues/3215)
### Build 1.2302.20 (February 20, 2023)
- LDAP: [Enabled ManageDsaIT Control for directory searches according to RFC 3296](https://www.rfc-editor.org/rfc/rfc3296)
### Build 1.2302.19 (February 19, 2023)
- LDAP: [Custom server certificates are cached for improved query performance](/pro/kb/ldap/#config-options)
- Config: [Advanced settings include additional options for PNGs and vector graphics](https://github.com/photoprism/photoprism/issues/2207#issuecomment-1436041896)
### Build 1.2302.18 (February 18, 2023)
- LDAP: [Added option to automatically chase referrals when there are multiple servers](/pro/kb/ldap/#config-options)
### Build 1.2302.16 (February 16, 2023)
- LDAP: [Updated config option defaults and documentation](/pro/kb/ldap/#custom-attributes)
### Build 1.2302.15 (February 15, 2023)
- Security: Go has been upgraded to v1.20.1, which includes many fixes and improvements
### Build 1.2302.14 (February 14, 2023)
- LDAP: [Specify a role for LDAP/AD users by providing a group DN with a placeholder for the role name](/pro/kb/ldap/#specifying-user-roles)
- Index: [Added file format support for Adobe Photoshop PSD and vector graphics](https://github.com/photoprism/photoprism/issues/2207)
- Index: [Added support for decoding JPEG XL and playing PNG animations](https://github.com/photoprism/photoprism/issues/3197)
### Build 1.2301.24 (January 24, 2023)
- LDAP: [Added support for using the UserPrincipalName as username for authentication](/pro/kb/ldap/#user-bind-dn)
### Build 1.2301.19 (January 19, 2023)
- UX: [Improved user interface layout for right-to-left languages](https://github.com/photoprism/photoprism/commit/3a1293d5d42ba8d0cf6f4efa1540a9db7f3681d9)
- UX: [Improved highlight and background colors in the cards view](https://github.com/photoprism/photoprism/commit/c243d45c118a6691c626397a9f81f08385ee6a60)
- PWA: [Increased allowed length of app name on home screen](https://github.com/photoprism/photoprism/commit/5dc71ff1ff69c157568c11d08b941b1d1875dc38) [and changed start URL](https://github.com/photoprism/photoprism/commit/4c81d8b7e18e2113bba6ef8e20158fecec89dc15)
- Themes: [Added "Carbon", "Neon", and "Nordic" based on colors from nordtheme.com](https://github.com/photoprism/photoprism/commit/93251d77a02a7de1ced8e28caf3deb2220a442c4)
- Themes: [Setting a custom favicon is now possible by adding it to the theme folder](/pro/kb/customization/#adding-a-favicon)
- Search: [Added `id:...` filter to find pictures by Exif UID, XMP Document ID or Instance ID](https://github.com/photoprism/photoprism/issues/3035)
- Search: [Increased batch size for better performance when loading results](https://github.com/photoprism/photoprism/issues/3009)
- Search: [Deleted albums are ignored when using the "unsorted" filter](https://github.com/photoprism/photoprism/issues/3051)
- Videos: [Improved player compatibility with browser plugins](https://github.com/photoprism/photoprism/issues/1439)
- Videos: [Improved preview image generation depending on duration](https://github.com/photoprism/photoprism/issues/1241#issuecomment-1363473310)
- Albums: [Added extended search form with sorting options](https://github.com/photoprism/photoprism/issues/353)
- Albums: [Fixed form field styles in the share dialog](https://github.com/photoprism/photoprism/commit/7c671e0dfc52936b1a3af426db1e0f5e165a12f7)
- Albums: [Double quotes in album names are replaced by Unicode characters](https://github.com/photoprism/photoprism/issues/2891)
- Folders: [Search is case-insensitive and uses wildcards for improved usability](https://github.com/photoprism/photoprism/issues/2050)
- Index: [Improved performance when flagging hidden files](https://github.com/photoprism/photoprism/issues/2928)
- Upload: [Estimated time remaining is displayed in minutes and seconds](https://github.com/photoprism/photoprism/issues/3049)
- Metadata: [GPS coordinates are normalized to be within a common range](https://github.com/photoprism/photoprism/issues/2109)
- CLI: [Added file extension flag to the `photoprism convert` command](https://github.com/photoprism/photoprism/issues/3038)
- Config: [Added the "audit-level" config option to change the threshold for recording events](/pro/kb/audit-logs/#config-options)
- Config: [Custom template path is not searched for files if not specified](https://github.com/photoprism/photoprism/issues/2946)
- Docker: [MariaDB image and binaries have been upgraded from v10.9 to v10.10](/pro/kb/quickstart/#step-1)
- Podman: [Added config examples for users of Red Hat-based Linux distributions](/pro/kb/quickstart/#step-1)
- Security: Go has been upgraded to v1.19.5, which includes security and stability fixes
- Translations: [Added Afrikaans (South Africa)](https://github.com/photoprism/photoprism/pull/3031/files)
- Translations: Updated Bulgarian, Chinese, Czech, Dutch, Estonian, French, German, Italian, Malay, Russian, and Ukrainian
## Personal Editions
- [PhotoPrism® Release Notes](https://docs.photoprism.app/release-notes/)
## Other Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Remote Setup
URL: https://www.photoprism.app/pro/kb/remote-setup/
> Get an overview of the process and requirements in case you would like us to perform a remote installation for you.
## Server Configuration
Depending on the size of your library and your performance expectations, a root or virtual server with at least 8 GB of RAM and a standard Linux distribution like Ubuntu 24.04 LTS is a good choice to run PhotoPrism® Pro.
More detailed [system requirements](/pro/kb/requirements/) and further information can be found in our [knowledge base](/pro/kb/).
### User Account & Permissions
It is recommended that you run the PhotoPrism and MariaDB services as non-root users. We therefore configure them to run under user ID 1000, unless you have asked us to use a different account. Currently, user IDs 0, 33, 50-99, 500-600, and 900-1200 are supported.
### Selecting Storage Folders
By default, we install PhotoPrism in `/opt/photoprism` so that:
- `/opt/photoprism/originals` is used as the *originals* folder for photo and video files,
- `/opt/photoprism/storage` is used as *storage* folder for config, cache, thumbnail and sidecar files,
- `/opt/photoprism/import` is used as *import* folder for transferring files to *originals*,
- and `/opt/photoprism/database` is used by MariaDB
> [!NOTE]
> If you want to use [other paths or volumes](/pro/kb/volumes/) on the server instead of the default folders, it is best to let us know in advance so that we can answer any questions you may have and prepare the configuration.
## Additional Considerations and Requirements
(1) **Server Access.** In order to perform the remote setup, we need (a) SSH access to the server and (b) must be able to use the sudo command (or have root privileges) so that we can install additional packages such as Docker if they are not already installed. We can provide you with a public key for SSH authentication upon request, otherwise we need (c) the password and of course (d) the hostname or IP address of the server. If a VPN is required to access your server, we ask that you use a standard solution that does not require the installation of proprietary or untrusted software on our computers. It is at our sole discretion to use the applications and tools you suggest or require.
(2) **Security Software.** If your server or virtual server host has additional security software installed, for example, endpoint security tools, centralized security management, or a virus scanner, it is your responsibility to ensure that it does not interfere with our software or its runtime dependencies, such as Docker, Docker Compose, Docker Desktop, Podman, or the operating system.
(3) **Firewall, DNS & Proxy Servers.** If you are using a firewall, you must (a) allow incoming requests to port 22 (SSH), 80 (HTTP), 443 (HTTPS), and/or 2342 (for unprivileged HTTP or HTTPS), and (b) outgoing connections, e.g. to our servers and Docker Hub, as described in the [corresponding Knowledge Base article](/pro/kb/firewall/) to successfully complete the installation. It is also your responsibility to ensure that any domain name servers (DNS) and proxy servers you may have in place do not block the domains or access to the domains required to run or install our software, and that their use is properly configured on the server.
(4) **Server Port, Domain & HTTPS.** In order for us to prepare the configuration, we should know in advance (a) which domain you want to use for the instance and (b) if you already have [HTTPS certificates](/pro/kb/https/) or if you want us to set up free Let's Encrypt certificates for you. Also let us know (c) if you want to use a non-standard port to access your instance, for example to avoid conflicts with other software. By default, PhotoPrism will listen on port 443 if HTTPS is enabled, and on port 2342 if you don't want us to enable HTTPS (not recommended). Any domains or subdomains you want to use must be configured to point to the server IP.
(5) **Config Options.** Please let us know how you want us to [configure your instance](/pro/kb/config-options/) based on the options available. Of course, you can change all the configuration values later, but we can help you more easily before the installation and answer any questions you may have.
(6) **Customer Account.** Before we start the installation, we ask that you [register on our website](https://my.photoprism.app/register) so that we can [assign the license](/pro/kb/activation/) to your personal account or your organization's customer account.
(7) **Media Library.** Although this is not strictly necessary, for example if you don't have any files yet or have privacy concerns, we recommend having at least a few media files on the server to test the installation.
## Scheduling the Installation Date
Once the server is ready and we have all the necessary information, we will be happy to [schedule an appointment](/contact/) for the remote setup.
Don't hesitate to [contact us](/contact/) if you have any questions.
## Problems During the Installation
We will be happy to schedule another appointment if we cannot access the server remotely on the day of installation, the user account provided to us does not have sufficient permissions, the server hardware does not meet the minimum requirements, or the server is running a non-standard or outdated operating system that we cannot easily work with.
> [!NOTE]
> Kindly note that scheduling another appointment is possible only once and that payments cannot be conditioned on prior installation if your offer includes remote setup as a complimentary service. Once we have started the installation, the subscription start date can also not be changed to a later date, even if you decide not to use our software in production immediately.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Search Filter Reference
URL: https://www.photoprism.app/pro/kb/search-filters/
> Get an overview of the supported search filters and learn how to use them.
| Filter | Type | Examples | Notes |
|:------------|:----------|:--------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| dist | decimal | dist:50 | Maximum distance to position in km |
| lat | decimal | lat:41.894043 | Position latitude (-90.0 to 90.0 deg) |
| lng | decimal | lng:-87.62448 | Position longitude (-180.0 to 180.0 deg) |
| chroma | number | chroma:70 | Chroma (0-100) |
| diff | number | diff:-1 diff:2 | Differential Perceptual Hash (000000-FFFFFF) |
| quality | number | quality:0 quality:3 | Minimum quality score (1-7) |
| album | string | album:berlin | Album UID or name, supports * wildcards |
| albums | string | albums:"South Africa & Birds" | Album names, combinable with & or \| |
| alt | string | alt:300-500 | Altitude (m) |
| camera | string | camera:canon | Camera make or model |
| caption | string | caption:"Lake*" | Searches text in captions separated by \|, or specify false to find content without a caption |
| category | string | category:airport | Location category type |
| city | string | city:"Berlin" | City names, separated by \| |
| codec | string | codec:avc1 | Media codec types separated by \|, e.g. jpeg, avc1, or hvc1 |
| color | string | color:"red\|blue" | Color name separated by \|, e.g. purple, magenta, pink, red, orange, gold, yellow, lime, green, teal, cyan, blue, brown, white, grey, or black |
| country | string | country:"de\|us" | Country codes, separated by \| |
| day | string | day:3\|13 | Days 1-31, separated by \| |
| description | string | description:"Lake*" | Searches text in titles or captions separated by \|, or specify false to find content without a title or caption |
| f | string | f:2.8-4.5 | Aperture (F-Number) |
| face | string | face:PN6QO5INYTUSAATOFL43LL2ABAV5ACZG | Find pictures with a specific face ID, you can also specify yes, no, new, or a face type |
| faces | string | faces:yes faces:3 | Minimum number of detected faces (yes means 1) |
| favorite | string | favorite:true favorite:false | Finds favorite content |
| filename | string | filename:"2021/07/12345.jpg" | File names including path and extension, separated by \| |
| folder | string | folder:"*/2020" | Alias for the path filter |
| geo | string | geo:yes | Finds content with or without latitude and longitude |
| hash | string | hash:2fd4e1c67a2d | SHA1 file hashes, separated by \| |
| id | string | id:123e4567-e89b-... | Finds content with the specified Image, Document or Instance IDs, separated by \| |
| iso | string | iso:200-400 | ISO number (light sensitivity) |
| keywords | string | keywords:"sand&water" | Keywords, combinable with & and \| |
| label | string | label:"cat\|dog&!blurry" | Label names: \| is OR within a group, & is AND between groups (every positive group must match), leading ! negates a group (e.g. !rejected). Category expansion applies to both positive and negative terms. Escape a literal &, \|, or leading ! with \ |
| latlng | string | latlng:49.4,13.41,46.5,2.331 | Position bounding box (Lat N, Lng E, Lat S, Lng W) |
| lens | string | lens:ef24 | Lens make or model |
| mm | string | mm:28-35 | Focal length (35mm equivalent) |
| month | string | month:7\|10 | Months from 1-12, separated by \| |
| mp | string | mp:3-6 | Resolution in Megapixels (MP) |
| name | string | name:"IMG_9831-112*" | File names without path and extension, separated by \| |
| near | string | near:pqbcf5j446s0futy | Finds nearby pictures (UID) |
| olc | string | olc:8FWCHX7W+ | Open Location Code (OLC) |
| original | string | original:"IMG_9831-112*" | Original file names of imported files, separated by \| |
| path | string | path:2020/Holiday | Path names separated by \|, supports * wildcards |
| people | string | people:"Jane & John" | Subject names, combinable with & or \| |
| person | string | person:"Jane Doe & John Doe" | Subject names, will be matched exactly and can be combined using & or \| |
| s2 | string | s2:4799e370ca54c8b9 | Position, specified as S2 Cell ID |
| scan | string | scan:true scan:false | Finds scanned photos and documents |
| state | string | state:"Baden-Württemberg" | State or province names, separated by \| |
| subject | string | subject:"Jane Doe & John Doe" | Alias for person |
| subjects | string | subjects:"Jane & John" | Alias for people |
| title | string | title:"Lake*" | Searches text in titles separated by \|, or specify false to find content without a title |
| type | string | type:image\|raw\|live | Finds specific media types, such as image, raw, live, video, animated, audio, vector, or document, separated by \| |
| uid | string | uid:pqbcf5j446s0futy | Finds content with the specified internal UIDs, separated by \| |
| year | string | year:1990\|2003 | Years, separated by \| |
| animated | switch | animated:yes | Finds animated images only |
| archived | switch | archived:yes | Finds archived content |
| audio | switch | audio:yes | Finds audio content only |
| document | switch | document:yes | Finds PDF documents only |
| error | switch | error:yes | Finds content with errors |
| hidden | switch | hidden:yes | Finds hidden content (broken or unsupported) |
| image | switch | image:yes | Finds regular photos and images only |
| landscape | switch | landscape:yes | Finds landscape pictures only |
| live | switch | live:yes | Finds Motion and Live Photos only |
| media | switch | media:yes | Finds live, video, audio, and animated content only |
| mono | switch | mono:yes | Pictures with few or no colors |
| panorama | switch | panorama:yes | Finds panorama pictures only (aspect ratio 1.9:1 or more) |
| photo | switch | photo:yes | Finds regular photos and images, as well as RAW and Live Photos |
| portrait | switch | portrait:yes | Finds portrait pictures only |
| primary | switch | primary:yes | Finds primary JPEG or PNG files only |
| private | switch | private:yes | Finds private content only (except when public:true) |
| public | switch | public:yes | Excludes private content |
| raw | switch | raw:yes | Finds RAW images only |
| review | switch | review:yes | Finds content in review |
| square | switch | square:yes | Finds square pictures only (aspect ratio 1:1) |
| stack | switch | stack:yes | Finds content with more than one media file |
| stackable | switch | stackable:yes | Finds content that can be stacked with additional files |
| unsorted | switch | unsorted:yes | Finds content that is not in an album |
| unstacked | switch | unstacked:yes | Finds content with a file that has been removed |
| vector | switch | vector:yes | Finds vector graphics only |
| video | switch | video:yes | Finds video content only |
| added | timestamp | added:"2006-01-02T15:04:05Z" | Finds content added at or after this time |
| after | timestamp | after:"2022-01-30" | Finds content created on or after this date |
| before | timestamp | before:"2022-01-30" | Finds content created before this date |
| edited | timestamp | edited:"2006-01-02T15:04:05Z" | Finds content edited at or after this time |
| taken | timestamp | taken:"2022-01-30" | Finds content created on the specified date |
| updated | timestamp | updated:"2006-01-02T15:04:05Z" | Finds content updated at or after this time |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Security Options
URL: https://www.photoprism.app/pro/kb/security/
> Get an overview of the additional security features and config options available to our business customers.
PhotoPrism® Pro includes the following additional config options, as well as more secure default settings to protect your instance by blocking vulnerability scanners and preventing the exploitation of newly discovered issues:
| Environment | CLI Flag | Default | Description |
|---------------------------------|------------------------|-------------|--------------------------------------------------------------------------------------------------|
| PHOTOPRISM_DISABLE_STS | --disable-sts | false | disables HTTP Strict-Transport-Security (STS) header |
| PHOTOPRISM_STS_SECONDS | --sts-seconds | 31536000 | `TIME` for the browser to remember that the site is to be accessed only via HTTPS (0 to disable) |
| PHOTOPRISM_STS_SUBDOMAINS | --sts-subdomains | false | applies rule to all subdomains |
| PHOTOPRISM_STS_PRELOAD | --sts-preload | false | allows submission to Google's HSTS preload service |
| PHOTOPRISM_REQUEST_LIMIT | --request-limit | 500 | maximum number of concurrent HTTP `REQUESTS` allowed from a single IP |
| PHOTOPRISM_REQUEST_INTERVAL | --request-interval | 5ms | average `DURATION` between HTTP requests from a single IP (0-1000ms) |
| PHOTOPRISM_LOGIN_LIMIT | --login-limit | 10 | maximum number of consecutive failed `LOGINS` from a single IP |
| PHOTOPRISM_LOGIN_INTERVAL | --login-interval | 1m0s | average `DURATION` between failed logins from a single IP (0-86400s) |
| PHOTOPRISM_IPS_LIMIT | --ips-limit | 3 | maximum number of malicious request `ATTEMPTS` before a client IP is blocked (-1 to disable) |
| PHOTOPRISM_IPS_INTERVAL | --ips-interval | 1h0m0s | average `DURATION` between malicious request attempts from a single IP (0-86400s) |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` |
| PHOTOPRISM_HTTP_CTO | --http-cto | nosniff | HTTP X-Content-Type-Options `HEADER` |
| PHOTOPRISM_HTTP_COOP | --http-coop | same-origin | HTTP Cross-Origin-Opener-Policy (COOP) `HEADER` |
| PHOTOPRISM_HTTP_REFERRER_POLICY | --http-referrer-policy | same-origin | HTTP Referrer-Policy `HEADER` |
| PHOTOPRISM_HTTP_FRAME_OPTIONS | --http-frame-options | DENY | HTTP X-Frame-Options `HEADER` |
| PHOTOPRISM_HTTP_HOSTNAME | --http-hostname | | serve requests for this `HOSTNAME` only |
## Using a Reverse Proxy
Advanced users can alternatively set the security headers listed above in combination with [a reverse proxy running in front of their instances](https://docs.photoprism.app/getting-started/proxies/traefik/) if they have special requirements. Please note, however, that our team can only provide you with limited technical support in this case and we only recommend this if you have the experience required.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Session Monitoring
URL: https://www.photoprism.app/pro/kb/monitoring/
> PhotoPrism® Pro's built-in session monitoring helps you find, examine, and, if necessary, remove user sessions.
## Admin Web UI
PhotoPrism® Pro includes a web user interface for account and session management. It allows you to conveniently manage user accounts and sessions when you log in as Admin and then navigate to *Settings > Users*.
## CLI Commands
You can use the following terminal commands to create, inspect and, if necessary, delete access tokens for the authentication of browsers and other clients (including [app passwords](https://docs.photoprism.app/user-guide/settings/account/#apps-and-devices)):
| CLI Command | Description |
|-------------------------------------|----------------------------------------------------------|
| `photoprism auth ls [search]` | Lists currently authenticated users and clients |
| `photoprism auth add [username]` | Adds a new authentication secret for client applications |
| `photoprism auth show [identifier]` | Shows detailed information about a session |
| `photoprism auth rm [identifier]` | Deletes a session by id or access token |
| `photoprism auth reset --yes` | Resets the authentication of all users and clients |
In addition, login attempts can be viewed in the application service logs as well as with this command:
```
docker compose exec photoprism photoprism audit logins [search]
```
### Command Options
You can combine the `sess ls` and `audit logins` commands with these flags to change the output format and the maximum number of search results:
| Command Flag | Description |
|--------------|----------------------------------------|
| `--md, -m ` | format as machine-readable Markdown |
| `--csv, -c` | export as semicolon separated values |
| `--tsv, -t` | export as tab separated values |
| `-n LIMIT` | LIMIT number of results (default: 100) |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Single Sign-On via OpenID Connect
URL: https://www.photoprism.app/pro/kb/openid-connect/
> OpenID Connect (OIDC) allows users to log in and optionally register through an external identity provider instead of manually entering a username and password.
## Config Options
| Environment | CLI Flag | Default | Description |
|-----------------------------|--------------------|------------------------------|-----------------------------------------------------------------------------------------------------|
| PHOTOPRISM_OIDC_URI | --oidc-uri | | issuer `URI` for single sign-on via OpenID Connect, e.g. https://accounts.google.com |
| PHOTOPRISM_OIDC_CLIENT | --oidc-client | | client `ID` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_SECRET | --oidc-secret | | client `SECRET` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_SCOPES | --oidc-scopes | openid email profile address | client authorization `SCOPES` for single sign-on via OpenID Connect |
| PHOTOPRISM_OIDC_PROMPT | --oidc-prompt | | authorization `PROMPT` for single sign-on via OpenID Connect (login, select_account, consent) |
| PHOTOPRISM_OIDC_PROVIDER | --oidc-provider | | custom identity provider `NAME`, e.g. Google |
| PHOTOPRISM_OIDC_ICON | --oidc-icon | | custom identity provider icon `URI` |
| PHOTOPRISM_OIDC_REDIRECT | --oidc-redirect | false | automatically redirects unauthenticated users to the configured identity provider |
| PHOTOPRISM_OIDC_REGISTER | --oidc-register | false | allows new users to create an account when they sign in with OpenID Connect |
| PHOTOPRISM_OIDC_LOGOUT | --oidc-logout | false | ends the provider session on sign-out via OpenID Connect RP-initiated logout |
| PHOTOPRISM_OIDC_USERNAME | --oidc-username | preferred_username | preferred username `CLAIM` for new OpenID Connect users (preferred_username, name, nickname, email) |
| PHOTOPRISM_OIDC_DOMAIN | --oidc-domain | | verified email domain `NAME` for single sign-on via OpenID Connect *pro* |
| PHOTOPRISM_OIDC_ROLE | --oidc-role | guest | default user `ROLE` for new OpenID Connect users *pro* |
| PHOTOPRISM_OIDC_GROUP_CLAIM | --oidc-group-claim | | group claim `NAME` to read from OIDC tokens (default groups) |
| PHOTOPRISM_OIDC_GROUP | --oidc-group | | require membership in at least one group `ID` (repeat flag to add multiple) |
| PHOTOPRISM_OIDC_GROUP_ROLE | --oidc-group-role | | map `GROUP=ROLE`; repeat to add more (roles: admin, manager, user, contributor, viewer, or guest) |
| PHOTOPRISM_OIDC_WEBDAV | --oidc-webdav | false | allows new OpenID Connect users to use WebDAV when they have a role that allows it |
| PHOTOPRISM_DISABLE_OIDC | --disable-oidc | false | disables single sign-on via OpenID Connect, even if an identity provider has been configured |
> [!NOTE]
> Your PhotoPrism instance and the [OpenID Connect Identity Provider (IdP)](#identity-providers) must be accessible **via HTTPS** and have valid TLS certificates configured for it. Please also make sure that the hostname in the [Redirect URL](#redirect-url) configured on the IdP matches the [Site URL](https://docs.photoprism.app/getting-started/config-options/#site-information) used by PhotoPrism. Single sign-on via OIDC can otherwise not be enabled.
## Identity Providers
To allow users to log in via OIDC, you can either set up and use a self-hosted identity provider such as [ZITADEL](https://zitadel.com/docs/self-hosting/deploy/compose) or [Keycloak](https://www.keycloak.org/), or choose a public authentication service such as those provided by [Google](https://developers.google.com/identity/openid-connect/openid-connect), [Microsoft](https://entra.microsoft.com/), [GitHub](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app), or [Amazon](https://developer.amazon.com/apps-and-games/login-with-amazon).
Single sign-on can then be configured automatically through your identity provider's `/.well-known/openid-configuration` [service discovery endpoint](https://developer.okta.com/docs/concepts/auth-servers/#discovery-endpoints-org-authorization-servers), for example:
- [https://accounts.google.com/.well-known/openid-configuration](https://accounts.google.com/.well-known/openid-configuration)
### Issuer URI
The [Issuer URI](#config-options) in your configuration must match the `issuer` value returned by the [`/.well-known/openid-configuration`](https://accounts.google.com/.well-known/openid-configuration) endpoint of your [OpenID Connect Identity Provider (IdP)](#identity-providers), for example `https://accounts.google.com` if you use Google for authentication.
> [!NOTE]
> You may not modify the URI in any way, e.g. by adding or omitting slashes at the end. If the values do not match, the validation will fail and users cannot be redirected to your provider's login page. For security reasons, only a generic error message is displayed in this case.
### Redirect URL
The Redirect URL that must be [specified when registering a new client](https://docs.photoprism.app/developer-guide/api/img/redirect-url-example.jpg) with an [Identity Provider](#identity-providers) is as follows, where `{hostname}` must be replaced by the hostname in the [Site URL](https://docs.photoprism.app/getting-started/config-options/#site-information), e.g. configured via `PHOTOPRISM_SITE_URL`:
```
https://{hostname}/api/v1/oidc/redirect
```
> [!NOTE]
> Note that both the [Site URL](https://docs.photoprism.app/getting-started/config-options/#site-information) configured for your instance and the Redirect URL must start with `https://` and that their hostnames must match, as the [use of secure connections](https://docs.photoprism.app/getting-started/using-https/) is a strict requirement for OpenID Connect.
## Authorization Prompt
By default, PhotoPrism does not ask your [identity provider](#identity-providers) for anything in particular when a user clicks the sign-in button. This keeps single sign-on seamless: a user who still has a session with the provider is signed in silently as the same account.
That is usually what you want, with one exception. When an account is not permitted to use the instance — because it has not been registered, or is not a member of a [required security group](#security-groups) — clicking the sign-in button again returns the same identity, and the user cannot choose a different account without signing out of the provider first.
Setting `PHOTOPRISM_OIDC_PROMPT` changes this by sending the OpenID Connect `prompt` parameter with the authorization request:
| Value | Effect |
|------------------|-----------------------------------------------------------------------------|
| `login` | The provider asks for credentials again, even if a session already exists |
| `select_account` | The provider shows its account chooser so a different account can be picked |
| `consent` | The provider shows its consent screen again |
You can combine values by separating them with a space, for example `PHOTOPRISM_OIDC_PROMPT="login consent"`. The value `none` is not accepted, as it would suppress the provider's own sign-in screen and break interactive logins; any value that is not recognized is ignored and sign-in continues as if no prompt had been configured.
> [!NOTE]
> In a [Portal-managed cluster](#cluster-authentication), set the prompt on the **Portal only** — it is the party that talks to your upstream provider. Instances authenticate against the Portal itself. [Learn more ›](/portal/kb/config-options/#authorization-prompt)
The effect depends on the provider honoring the parameter. Most support `login`, while support for the account chooser (`select_account`) varies.
## Single Sign-Out
Signing out of PhotoPrism ends the PhotoPrism session. It does **not** end the session a user has with your [identity provider](#identity-providers), so clicking the sign-in button again signs them straight back in.
Set `PHOTOPRISM_OIDC_LOGOUT` to `"true"` to also end the provider session on sign-out, using [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). The next sign-in then asks for credentials again. Users who sign in with a local password are not affected.
Two things are required on the provider side:
1. Your provider must advertise an `end_session_endpoint` in its [`/.well-known/openid-configuration`](#identity-providers) document. PhotoPrism reads it from there — there is no logout URL to configure. If the provider advertises none, sign-out stays local.
2. The provider's client must have the **post-logout redirect URI** registered. PhotoPrism returns users to its own login page, where `{hostname}` must be replaced by the hostname in the [Site URL](https://docs.photoprism.app/getting-started/config-options/#site-information):
```
https://{hostname}/library/login
```
Depending on the provider, you can register that URL, or a wildcard for the same host such as `https://{hostname}/*`.
> [!NOTE]
> **Register the URI before enabling this option.** If the post-logout redirect URI has not been registered, the provider rejects the request with an error such as *"Invalid redirect uri"*, the provider session is **not** ended, and the user is left on an error page of the provider instead of the PhotoPrism login page.
> [!NOTE]
> In a [Portal-managed cluster](#cluster-authentication), sign-out cascades instance → Portal → upstream provider, so enable `PHOTOPRISM_OIDC_LOGOUT` on the instances **and** on the Portal for the chain to reach your provider. Register each instance login page, or a shared-domain wildcard, on the provider client. [Learn more ›](/portal/kb/config-options/#single-sign-out)
Sign-out is initiated by PhotoPrism. The provider-initiated back-channel and front-channel logout profiles are not part of this feature.
## Preferred Username
When a new user signs in with OpenID Connect[^1], their preferred username may already be registered. In this case, a random 6-digit number is appended to resolve the conflict.
The config option `PHOTOPRISM_OIDC_USERNAME` allows you to change the [preferred username](#config-options) claim for new accounts from `preferred_username` to `name`, `nickname` or verified[^2] `email`. The other claims are used as fallback if no value is returned for the configured claim. Names are changed to lowercase so that, for example, "John Doe" becomes "john.doe".
[Learn more ›](#can-i-configure-a-custom-claim-for-the-preferred-username)
## Existing Accounts
[Super admins](/pro/kb/roles/#admin) can manually connect existing user accounts[^3] under [*Settings > Users*](https://docs.photoprism.app/user-guide/users/) by changing the authentication to *OIDC* and then setting the *Subject ID* to match the account identifier from the configured [Identity Provider](#identity-providers):
The *Edit Account* dialog may additionally contain a text field for the *Issuer* URL. It does not need to be entered manually as it is set automatically after the first login.
Alternatively, you can [run the following command](https://docs.photoprism.app/user-guide/users/cli/#command-options) in [a terminal](https://docs.photoprism.app/getting-started/docker-compose/#opening-a-terminal) to allow authentication via *OIDC* and set a *Subject ID* to connect existing accounts:
```bash
photoprism users mod --auth=oidc --auth-id=[sub] [username]
```
[Learn more ›](https://docs.photoprism.app/user-guide/users/cli/#command-options)
### Passwords
Changing the authentication of an account to *OIDC* does not remove a previously set password, so that it can still be used to log in (optionally also in combination with [2FA](https://docs.photoprism.app/user-guide/users/2fa/)).
If a [local password](https://docs.photoprism.app/user-guide/users/cli/#changing-a-password) has been set for an account, you can remove it by running the following command [in a terminal](https://docs.photoprism.app/user-guide/users/cli/#removing-a-password):
```bash
photoprism passwd --rm [username]
```
[Super admins](/pro/kb/roles/#admin) can alternatively set the account password to a long random value through the [Admin Web UI](https://docs.photoprism.app/user-guide/users/#changing-passwords) or [CLI](https://docs.photoprism.app/user-guide/users/cli/#changing-a-password) to effectively prevent local authentication.
[Learn more ›](https://docs.photoprism.app/user-guide/users/cli/#removing-a-password)
### Deleting Accounts
Deleted accounts remain linked to the *Subject ID*, so logging in via *OIDC* is no longer possible and no new account can be registered for the same *Subject ID* either.
If you wish to change the connected user account or create a new account instead, you must therefore [change the authentication](https://docs.photoprism.app/user-guide/users/#editing-user-details) of the old account e.g. to *None* before [deleting it](https://docs.photoprism.app/user-guide/users/#deleting-a-user):
```bash
photoprism users mod --auth=none [username]
```
To restore a previously deleted account, admins can follow the same steps as for [creating a new account](https://docs.photoprism.app/user-guide/users/cli/#creating-a-new-account) with the same *username* through the [Admin Web UI](https://docs.photoprism.app/user-guide/users/#adding-a-new-user) or the [`photoprism users add`](https://docs.photoprism.app/user-guide/users/cli/#creating-a-new-account) command. You will then be asked if you want to restore the account.
[Learn more ›](https://docs.photoprism.app/user-guide/users/cli/#creating-a-new-account)
## Using Security Groups from Microsoft Entra ID
The following features are supported:
- Security groups are read from the `groups` claim in ID or access tokens. Both GUIDs and group names are accepted and are normalized before they are compared, so the case you use in your configuration does not matter.
- Membership can be made a requirement: `--oidc-group` (or `PHOTOPRISM_OIDC_GROUP`) lists one or more groups that must be present, and sign-in is rejected when none of them match. When a token indicates that the group list was too large to be included (Microsoft's *group overage*, signaled through `_claim_names.groups`) and carries no groups, sign-in is likewise rejected and the reason is recorded in the audit log.
- Groups are mapped to roles with `--oidc-group-role` (`GROUP=ROLE`, repeatable); the first match wins, and `--oidc-role` (default `guest`) applies when no mapping matches.
- Application and directory roles (`roles`, `wids`) are kept separate from security groups, so a directory role cannot raise a user's privileges by accident.
- The claim to read is configurable with `--oidc-group-claim` (default `groups`).
You can use the following config options to map security groups and roles in PhotoPrism® Pro:
- `--oidc-group-claim` / `PHOTOPRISM_OIDC_GROUP_CLAIM`: claim to read (default `groups`).
- `--oidc-group` / `PHOTOPRISM_OIDC_GROUP`: comma- or multi-flag list of groups required for login (IDs or names accepted, normalized to lowercase alphanumerics/hyphen/underscore).
- `--oidc-group-role` / `PHOTOPRISM_OIDC_GROUP_ROLE`: mapping `GROUP=ROLE` (roles: `admin|manager|user|contributor|viewer|guest|none`). First match wins.
- `--oidc-role` / `PHOTOPRISM_OIDC_ROLE`: fallback role if no group mapping matches (defaults to `guest`).
> [!NOTE]
> Support for Entra ID Security Groups is only available with our [team plans](/teams/#compare), not the [personal editions](/editions/#compare).
### Integration Guide for Entra ID Groups
1. Register an app in Microsoft Entra ID (v2) or reuse your existing PhotoPrism registration. Note the tenant ID and the application (client) ID.
2. Redirect URI: add [`https://{hostname}/api/v1/oidc/redirect`](https://docs.photoprism.app/getting-started/advanced/openid-connect/#redirect-url).
3. Token configuration → **Add optional claim** → **Token type** = ID (and Access if you prefer) → **Groups** → choose **Security groups**.
4. Under “Emit groups as”, pick **Group name** (cloud-only) or **sAMAccountName** / **DNSDomainName\sAMAccountName** for synced AD; this makes tokens carry human-friendly names instead of GUIDs.
5. If you keep **Group ID**, leave PhotoPrism config in GUID mode; if you emit names, set `PHOTOPRISM_OIDC_GROUP` / `PHOTOPRISM_OIDC_GROUP_ROLE` to those names (lowercase in config for consistency). When Microsoft signals group **overage** (too many groups to fit in the token), it sets `_claim_names.groups` and may omit groups entirely; PhotoPrism will currently block login if required groups are configured and no groups are present.
6. Grant admin consent for the chosen scopes (at minimum `openid profile email`, plus `offline_access` if you need refresh tokens).
7. Configure PhotoPrism (example `.env-oidc` with placeholder secrets):
```
PHOTOPRISM_OIDC_URI="https://login.microsoftonline.com/f8b10857-a7f2-49ba-b73c-6f619715f574/v2.0"
PHOTOPRISM_OIDC_CLIENT="11111111-2222-3333-4444-555555555555"
PHOTOPRISM_OIDC_SECRET="asecure-random-oidc-client-secret"
PHOTOPRISM_OIDC_GROUP_CLAIM="groups"
PHOTOPRISM_OIDC_GROUP="photoprism-admins, photoprism-users" # names or GUIDs
PHOTOPRISM_OIDC_GROUP_ROLE="photoprism-admins=admin, photoprism-users=user"
```
8. Restart PhotoPrism; on login the service will:
- Read groups from ID token, then fall back to userinfo if absent.
- Deny login if required groups are configured but none are present (and overage is signaled).
- Apply the first matching group→role mapping; otherwise assign the fallback role.
Usage Tips
- If tokens still contain GUIDs, revisit Token configuration → Groups and change “Emit groups as” to a name format; reissue tokens by signing out/in. Names must be unique in your tenant for deterministic mapping.
- Overage: when the `_claim_names.groups` marker is present and no groups are in the token, PhotoPrism cannot validate membership and blocks sign-in if `oidc-group` is set. Resolving the full group list through Microsoft Graph is not supported, so reduce the number of groups emitted into the token — for example by restricting the group claim to groups assigned to the application — if you run into this.
- For mixed environments, you can supply both names and GUIDs in `oidc-group` / `oidc-group-role`; all entries are normalized and deduplicated.
### Documentation & References
- Microsoft Entra ID:
We recommend testing the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license.
## Firewall
In order to successfully set up your installation and view location details in PhotoPrism® Pro, you must **allow requests to Docker Hub and our geocoding API** if you have a firewall installed, and make sure your internet connection is working.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# UI Customization
URL: https://www.photoprism.app/pro/kb/customization/
> In this guide, we show you how to customize the look of PhotoPrism® Pro to match your branding or corporate identity.
## Specifying a Custom Theme
The easiest way to change the look of the user interface is to add a custom theme. To do this, create the file `config/theme/app.js` in the *storage* folder and insert the following with a text editor:
```js
window.__THEMES__ = [
{
"dark": true,
"force": true,
"title": "Custom",
"name": "custom",
"colors": {
"background": "#2c2d2f",
"surface": "#161718",
"on-surface": "#ffffff",
"surface-bright": "#333333",
"surface-variant": "#7E4FE3",
"on-surface-variant": "#f6f7e8",
"card": "#171718",
"table": "#1F2022",
"button": "#1D1E1F",
"switch": "#101112",
"primary": "#9E7BEA",
"highlight": "#5F1DB7",
"selected": "#4d4d4e",
"secondary": "#191A1C",
"secondary-light": "#1E2022",
"accent": "#2D2E2E",
"error": "#e57373",
"info": "#00acc1",
"success": "#4db6ac",
"warning": "#ffd740",
"favorite": "#FFD600",
"remove": "#da4e4c",
"restore": "#00d48a",
"album": "#ed9e00",
"download": "#00bfa5",
"private": "#00b8d4",
"edit": "#2196F3",
"share": "#3F51B5",
"love": "#ef5350",
"terminal": "#4A464F",
"navigation": "#141417",
"navigation-home": "#0e0f10"
},
variables: {
"btn-height": "34px",
"table-row-height": "44px",
"table-header-height": "44px",
"border-color": "#FFFFFF",
"border-opacity": 0.05,
"high-emphasis-opacity": 0.96,
"medium-emphasis-opacity": 0.88,
"label-opacity": 0.67,
"disabled-opacity": 0.75,
"idle-opacity": 0.1,
"fill-opacity": 0.04,
"hover-opacity": 0.019,
"focus-opacity": 0.022,
"selected-opacity": 0.08,
"activated-opacity": 0,
"pressed-opacity": 0.16,
"dragged-opacity": 0.08,
"overlay-color": "#131313",
"overlay-opacity": 0.54,
"theme-kbd": "#212529",
"theme-on-kbd": "#FFFFFF",
"theme-code": "#343434",
"theme-on-code": "#CCCCCC",
"icon": "logo.svg"
}
}
];
```
This allows you to change the title and colors of the theme according to your preferences. For light theme colors, set the “dark” property to false. You can also set “force” to false to let the user decide whether to use the custom theme or one of the built-in themes. The login screen theme can be overridden by additionally specifying a theme named “login” in the `__THEMES__` array.
The `icon` field sets the logo shown in the app and on the login screen. Specify the file name of an image placed in your theme folder, for example `logo.svg` for `config/theme/logo.svg`; PhotoPrism resolves it relative to the theme directory and automatically prefixes it with the site's base URL, so the logo also loads when the app is served under a sub-path, such as in a multi-instance cluster. A root-relative `/_theme/...` path or an absolute URL, for example a link to an external CDN, can be used as well.
> [!NOTE]
> When testing how the changes look, make sure to clear the browser cache and try the UI with different window sizes, as our UI styles are responsive. If you add custom styles, you should also ensure that they work with different resolutions and screen aspect ratios.
## Adding a Favicon
To set a custom favicon, you can simply add a suitable PNG image with the filename `config/theme/favicon.png` to your theme in the *storage* folder. It will be automatically detected and included in the generated page headers and web application manifest.
## Changing UI Styles
In addition to customizing the basic theme colors and setting a favicon image, you can further customize the look of the user interface by setting custom CSS styles in a `config/theme/app.css` file located in the *storage* folder. Examples can be found in our [public project repository](https://github.com/photoprism/photoprism/blob/develop/frontend/src/css/themes.css).
This allows you to customize almost every detail of the app's appearance. We just ask that you do not remove, obscure, or alter any copyright notices or PhotoPrism's names, trademarks, hyperlinks, or other designations displayed in the Software as set forth in the [license agreement](/pro/license/).
Any additional assets you need for your styles can also be placed in the *theme* folder. Since `app.css` is served from this folder, reference them with a relative URL, for example `url(logo.svg)` or `url(./background.jpg)`, so that they resolve correctly whether PhotoPrism is hosted at the site root or under a sub-path, as in a multi-instance cluster.
## Customizing the Login Screen
The login screen theme can be overridden by specifying a theme named "login" in the `__THEMES__` array shown above. Its colors style the login page, and its `icon` field sets the logo shown there independently of the in-app logo. To change the login screen background, set the `PHOTOPRISM_WALLPAPER_URI` config option to the file name of an image in your theme folder or to an external image URL.
## Using Custom Fonts
By default, the PhotoPrism UI is optimized for rendering performance and thus uses the operating system font, so the browser does [not need to wait for fonts to download](https://web.dev/font-best-practices/#use-fewer-web-fonts). This approach also provides the best integration with native apps that typically use the default Windows, Android, iOS, or macOS font.
If you want to set a custom font for all users, we recommend testing the application for side effects, as we have observed alignment issues with some fonts in the past.
> [!NOTE]
> We generally do not take responsibility for performance or layout issues resulting from the use of custom fonts and styles.
## Getting a Branded Theme
Our team will be happy to [create a branded theme for you](/teams/#compare) based on the colors of a style guide or an existing website. In order for us to create the theme, we ask that you provide us with all assets and materials to be used. If you would like additional changes, such as a custom font or layout changes, please contact us for a [custom quote](/contact/).
## Config Options
The following is a list of [config options](/pro/kb/config-options/) that can affect the user interface, for example by changing background images, icons, and links:
| Environment | CLI Flag | Default | Description |
|-------------------------------|----------------------|-------------------------------------|-------------------------------------------------------------------------|
| PHOTOPRISM_PASSWORD_RESET_URI | --password-reset-uri | | custom password reset page `URI` *pro* |
| PHOTOPRISM_REGISTER_URI | --register-uri | | custom registration page `URI` *pro* |
| PHOTOPRISM_LOGIN_INFO | --login-info | | custom login footer info `TEXT` *pro* |
| PHOTOPRISM_DEFAULT_LOCALE | --default-locale | en | default user interface language `CODE` |
| PHOTOPRISM_DEFAULT_TIMEZONE | --default-timezone | Local | default time zone `NAME`, e.g. for scheduling backups |
| PHOTOPRISM_DEFAULT_THEME | --default-theme | | default user interface theme `NAME` |
| PHOTOPRISM_APP_NAME | --app-name | | app `NAME` when installed as a Progressive Web App (PWA) |
| PHOTOPRISM_APP_MODE | --app-mode | standalone | app display `MODE` (fullscreen, standalone, minimal-ui, browser) |
| PHOTOPRISM_APP_ICON | --app-icon | | home screen app `ICON` (logo, app, crisp, mint, bold, square) |
| PHOTOPRISM_APP_COLOR | --app-color | #19191a | app background and splash screen `COLOR` |
| PHOTOPRISM_LEGAL_INFO | --legal-info | | legal information `TEXT`, displayed in the page footer |
| PHOTOPRISM_LEGAL_URL | --legal-url | | legal information `URL` |
| PHOTOPRISM_WALLPAPER_URI | --wallpaper-uri | | login screen background image `URI` |
| PHOTOPRISM_SITE_URL | --site-url | | canonical site `URL` used in generated links and to determine HTTPS/TLS |
| PHOTOPRISM_SITE_AUTHOR | --site-author | | site `OWNER` shown in the author meta tag |
| PHOTOPRISM_SITE_NAME | --site-name | | short `NAME` for identifying this instance within a cluster *optional* |
| PHOTOPRISM_SITE_TITLE | --site-title | | main `TITLE` shown in the web interface and meta tags |
| PHOTOPRISM_SITE_CAPTION | --site-caption | AI-Powered Digital Asset Management | site `CAPTION` *pro* |
| PHOTOPRISM_SITE_DESCRIPTION | --site-description | | longer `DESCRIPTION` shown in SEO and social meta tags *optional* |
| PHOTOPRISM_SITE_FAVICON | --site-favicon | | custom favicon `FILENAME` for web browsers *optional* |
| PHOTOPRISM_SITE_PREVIEW | --site-preview | | sharing preview image `URL` |
> [!NOTE]
> If you change global configuration values in your `compose.yaml` or `docker-compose.yml` file or in the Advanced Settings UI, a restart is required for these changes to take effect.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Upgrade Guide
URL: https://www.photoprism.app/pro/kb/upgrade/
> Learn how to upgrade to PhotoPrism® Pro if you already have PhotoPrism installed.
## Step 1: Create a Customer Account ##
Before you proceed, please make sure you have a customer account with us. You can register using the link you have [received from us by email](mailto:support@photoprism.app). If you already have an account, we will be happy to [assign your licenses](mailto:support@photoprism.app) to that account or give you [a free trial](mailto:sales@photoprism.app).
> [!NOTE]
> Our [Privacy Policy](/privacy/) explains what information we collect and how we use it. Don't hesitate to [contact us](/contact/) if you have any questions about this policy, other privacy-related topics, or the registration process.
## Step 2: Upgrade to PhotoPrism® Pro ##
If you already have our [Community Edition](https://docs.photoprism.app/getting-started/) installed or are upgrading from [PhotoPrism® Plus](/plus/), you can keep your existing configuration and only need to change the Docker image.
(1) Change the Docker image in your `compose.yaml` from `photoprism/photoprism:latest` to `photoprism/pro:latest` and save your changes:
```yaml
services:
photoprism:
image: photoprism/pro:latest
```
> [!NOTE]
> When **[using Portainer](/pro/kb/portainer/)** you can change the image by navigating to "Stacks", selecting your existing PhotoPrism stack, clicking "Editor" and changing the photoprism image to `photoprism/pro:latest` as shown above. When you are done, scroll down, click "Update the stack", enable the "re-pull and redeploy" option, click "Update" and skip the next steps.
(2) Restart your instance as follows to complete the upgrade:
```
docker compose pull
docker compose up -d
```
PhotoPrism® Pro should be ready to use after waiting a few moments, so you can connect to the same URL you have been using before and log in with one of the existing accounts.
> [!NOTE]
> Note that the examples in our documentation use the new `docker compose` command by default. If your server does not yet support it, the old `docker-compose` command will continue to work.
> [!NOTE]
> To verify that all services are running properly, you can view the server logs at any time by running `docker compose logs -f`.
## Step 3: Get Started ##
Our [First Steps 👣](https://docs.photoprism.app/user-guide/first-steps/) tutorial guides you through the user interface and library settings to ensure your library is indexed according to your individual preferences.
In the following section, we'll give you an overview of the available user roles in PhotoPrism® Pro and show you how to manage accounts.
### User Management ###
In addition to the command-line interface available in all editions, PhotoPrism® Pro includes a web user interface for managing user accounts as well as additional account roles to restrict permissions as needed.
### Authenticating Users Against a Directory Server ###
With the built-in LDAP support, you can authenticate users against a central [Lightweight Directory Access Protocol](https://ubuntu.com/server/docs/service-ldap) or [Active Directory (AD)](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-ldap) server so that users on the corporate network can sign in with their existing usernames and passwords.
### Using Audit Logs ###
Audit logs help your security, auditing, and compliance entities monitor PhotoPrism® Pro for potential vulnerabilities, misuse, and other critical incidents.
### Hardened Web Security ###
PhotoPrism® Pro additionally includes advanced security features such as session monitoring (run `photoprism auth --help` to see the available commands), which allows you to create, inspect and delete access tokens for authenticating browsers and other clients (including [app passwords](https://docs.photoprism.app/user-guide/settings/account/#apps-and-devices)). You can also set a general request rate limit for the built-in web server and a threshold for failed login attempts.
For more information on the available security options, see the *Authentication* and *Web Server* sections in our [configuration options](/pro/kb/config-options/) overview.
### Using HTTPS ###
For **HTTPS** to work with your own domains, you can either [use an HTTPS reverse proxy like Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/) (that you might already have to run other services) or specify a TLS certificate and private key file via `PHOTOPRISM_TLS_CERT` and `PHOTOPRISM_TLS_KEY` in your *compose.yaml* file.
## PhotoPrism® Documentation ##
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Using a Content Delivery Network
URL: https://www.photoprism.app/pro/kb/using-a-cdn/
> Configuring a CDN can effectively reduce server load and improve user experience.
A *Content Delivery Network* is a distributed network of servers that can deliver static content to users around the world.
## When to use a CDN?
**Large Media Files:** PhotoPrism stores photos and videos that can be very large. A CDN can help speed up the delivery of these files to users.
**Global Audience:** If your PhotoPrism instance is accessed from different locations around the world, a CDN can help reduce latency and improve the overall user experience by delivering content from servers that are closer to your users.
**Many Users:** If your PhotoPrism instance is getting a lot of traffic, a CDN can improve application performance by reducing the load on your server.
## Config Options
You can use the following config options to specify the URL of an external CDN and change the cache expiration time for thumbnails and other static content:
| Environment | CLI Flag | Default | Description |
|------------------------------|---------------------|---------|-------------------------------------------------------------|
| PHOTOPRISM_CDN_URL | --cdn-url | | content delivery network `URL` |
| PHOTOPRISM_CDN_VIDEO | --cdn-video | false | stream videos over the specified CDN |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` |
| PHOTOPRISM_HTTP_CACHE_PUBLIC | --http-cache-public | true | allow static content to be cached by a CDN or caching proxy |
| PHOTOPRISM_HTTP_CACHE_MAXAGE | --http-cache-maxage | 2592000 | time in `SECONDS` until cached content expires |
| PHOTOPRISM_HTTP_VIDEO_MAXAGE | --http-video-maxage | 21600 | time in `SECONDS` until cached videos expire |
> [!NOTE]
> `PHOTOPRISM_HTTP_CACHE_PUBLIC` is enabled automatically as soon as a `PHOTOPRISM_CDN_URL` is
> configured, which is why it defaults to `true` here; without a CDN it defaults to `false`, as
> shown in the [config reference](/pro/kb/config-options/#web-server). Publicly cacheable content can be
> served by a CDN or caching proxy without accessing your instance if it is already cached.
## CDN Providers
### bunny.net
If you don't have a CDN provider yet, we can recommend [bunny.net](https://link.photoprism.app/bunny-cdn). This EU-based company has a cute name, but is a reputable provider with [excellent performance](https://www.cdnperf.com/), a wide range of features, and more than 20,000 customers including big names like Hyundai. We also chose bunny.net for our website and public demo as they are fully compliant with the GDPR.[^1]
Pricing starts at $0.005/GB and there is no minimum usage or monthly fee, so you only pay for what you actually need.
[Learn more ›](https://link.photoprism.app/bunny-cdn)
### Cloudflare
[Cloudflare](https://www.cloudflare.com/) works similar to a [reverse proxy](https://docs.photoprism.app/getting-started/proxies/traefik/), allowing you to make a private server publicly accessible over the Internet. This means that users accessing your instance through their service will only see a single URL, as if they were connecting directly.
You must therefore not configure an external CDN URL, since this could prevent PhotoPrism from loading. Also note that their free version [does not include video streaming](https://www.cloudflare.com/plans/), so there may be problems with video playback if you are not a paying customer.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
[^1]: We receive a $20 credit when you sign up through our link, which helps us fund the project infrastructure.
---
# Using Audit Logs
URL: https://www.photoprism.app/pro/kb/audit-logs/
> Audit logs help your security, auditing, and compliance entities monitor PhotoPrism® Pro for potential vulnerabilities, misuse, and other critical incidents.
Recorded information includes the time of the incident, the severity, the responsible IP and user or session, and the action, such as a failed authorization check. For security reasons, audit logs are not visible on the regular web user interface and can only be viewed in the application service logs or searched in a terminal using the CLI commands documented below.
### Severity Levels
| Severity | Log Level | Description |
|----------|-----------|---------------------------------------------------------|
| alert | panic | security alert, e.g. an attack has been detected |
| critical | fatal | critical security incidents and application errors |
| error | error | failed authorization checks, application errors |
| warning | warning | file deletions, failed logins, and invalid api requests |
| info | info | expected and uncritical actions e.g. file uploads |
| debug | debug | informational messages, e.g. successful logouts |
### Config Options
The general verbosity level of log messages can be set with `PHOTOPRISM_LOG_LEVEL`. In addition, incidents with a level equal to or higher than `PHOTOPRISM_AUDIT_LEVEL` are recorded in the database in a structured way so that they can be searched.
| Environment Variable | CLI Flag | Default | Description |
|------------------------|---------------|---------|----------------------------------------------------------------------------------|
| PHOTOPRISM_LOG_LEVEL | --log-level | info | log message verbosity `LEVEL` (trace, debug, info, warning, error, fatal, panic) |
| PHOTOPRISM_AUDIT_LEVEL | --audit-level | warning | audit log recording `LEVEL` (debug, info, warning, error, fatal, panic) |
### Audit Commands
Use the following terminal commands to search the database for login attempts, user actions and incidents, or application errors:
| Command | Description |
|-------------------------------------|-------------------------|
| `photoprism audit logins [search]` | Displays login attempts |
| `photoprism audit logs [search]` | Displays audit logs |
| `photoprism audit errors [search]` | Displays error logs |
You can combine them with these flags to change the output format and the maximum number of search results:
| Command Flag | Description |
|--------------|----------------------------------------|
| `--md, -m ` | format as machine-readable Markdown |
| `--csv, -c` | export as semicolon separated values |
| `--tsv, -t` | export as tab separated values |
| `-n LIMIT` | LIMIT number of results (default: 100) |
> [!NOTE]
> Run `photoprism audit clear` to clear all recorded incidents and reset the database to a clean state.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Using HTTPS
URL: https://www.photoprism.app/pro/kb/https/
> In this guide, we show you how to enable transport encryption, add server certificates, and create new certificates.
## Why Use Encryption?
If you install PhotoPrism on a shared server so that it is not only accessible to the local host, always **secure the connection using HTTPS**. Your files and passwords will otherwise be transmitted in clear text and can be intercepted by anyone, including your provider, hackers, and governments. Backup tools and file synchronization apps may also refuse to connect.
> [!NOTE]
> HTTPS connections use Transport Layer Security (TLS) for encryption. TLS is a network protocol that establishes an encrypted connection to an authenticated peer over an untrusted network.
## How To Enable HTTPS
You have the following options to enable HTTPS/TLS when using our [latest stable release](/pro/kb/release-notes/).
Note that after adding or updating certificates, it is required to restart PhotoPrism for the changes to take effect.
### 1. HTTPS Reverse Proxy
To run your instance behind an [HTTPS reverse proxy like Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/), we recommend that you explicitly disable TLS in PhotoPrism by setting `PHOTOPRISM_DISABLE_TLS` to `"true"` in your `compose.yaml` configuration:
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_DISABLE_TLS: "true"
```
> [!NOTE]
> Especially if your server also has other web applications installed and/or a proxy with working HTTPS is already in place, this may be the best option.
### 2. Self-Signed Certificate
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_DISABLE_TLS: "false"
PHOTOPRISM_DEFAULT_TLS: "true"
PHOTOPRISM_INIT: "https"
```
### 3. Custom Certificate
To use your own certificates, you can add a custom TLS certificate and private key to the `storage/config/certificates` folder with the filenames `www.example.com.crt` and `www.example.com.key`, replacing `www.example.com` with the actual server domain. For this, you can set the same config options as when using a self-signed certificate (see above).
Alternatively, you can specify a custom TLS certificate (`*.crt`) and private key (`*.key`) filename within the `storage/config/certificates` folder using the `PHOTOPRISM_TLS_CERT` and `PHOTOPRISM_TLS_KEY` [environment variables](https://docs.photoprism.app/getting-started/config-options/) in your `compose.yaml`, or use the corresponding [command flags](https://docs.photoprism.app/getting-started/config-options/):
```yaml
services:
photoprism:
# ...
environment:
PHOTOPRISM_SITE_URL: "https://www.example.com/"
PHOTOPRISM_TLS_CERT: "site.crt"
PHOTOPRISM_TLS_KEY: "site.key"
PHOTOPRISM_DISABLE_TLS: "false"
PHOTOPRISM_DEFAULT_TLS: "true"
PHOTOPRISM_INIT: "https"
```
> [!NOTE]
> We recommend that you keep the `PHOTOPRISM_DEFAULT_TLS` option enabled so that you can always connect securely over HTTPS even if there is a problem with your custom certificates.
## Obtaining Certificates
Valid server certificates can be obtained either from a commercial [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) (CA) like [ZeroSSL](#zerossl) or free of charge from [Let's Encrypt](#lets-encrypt):
### Let’s Encrypt
[Let's Encrypt](https://letsencrypt.org/) is an automatic certificate authority that provides you with free HTTPS/TLS certificates. Many web servers and reverse proxies such as [Traefik](https://docs.photoprism.app/getting-started/proxies/traefik/) and [Caddy](https://docs.photoprism.app/getting-started/proxies/caddy-2/) have integrated support for obtaining single-domain certificates if your server is accessible on port 80 over the public Internet.
The creation of certificates for servers that are not publicly reachable or that are valid for all subdomains (wildcard) is alternatively possible with the [LEGO Let's Encrypt client](https://go-acme.github.io/lego/usage/cli/obtain-a-certificate/). If you use Docker and [DigitalOcean's free DNS service](https://m.do.co/c/f9725a28bb6b), the [command to run](https://go-acme.github.io/lego/usage/cli/obtain-a-certificate/) will look as follows (replace the certificate path, access token, domain names, and email address with the appropriate values):
```bash
docker run --rm -v "/path/to/certificates:/data/" \
-e DO_AUTH_TOKEN=Your_Access_Token goacme/lego -a \
-d "example.com" -d "*.example.com" --email="you@example.com" \
--dns=digitalocean --dns-timeout=180 --path=/data run
```
Note that this verification method only works if you use a [supported DNS provider](https://go-acme.github.io/lego/dns/) that LEGO can access through an API. Please refer to [its documentation](https://go-acme.github.io/lego/dns/) for details, as each provider requires different authentication credentials. If you are [using DigitalOcean](https://m.do.co/c/f9725a28bb6b), you can create the required access token in [your customer dashboard](https://cloud.digitalocean.com/account/api/tokens) and replace `Your_Access_Token` with it.
### ZeroSSL
[ZeroSSL](https://link.photoprism.app/zerossl) is a widely trusted commercial certificate authority with more than 500,000 customers worldwide. Its headquarters are located in [Vienna, Austria](https://link.photoprism.app/zerossl-contact).
Compared to Let's Encrypt, you can also create and revoke certificates through a user-friendly web interface, obtain certificates with a validity of more than 90 days, and choose between additional domain verification methods.[^1]
[Learn more ›](https://link.photoprism.app/zerossl)
## Troubleshooting
### Enabling Trace Log Mode
A good way to troubleshoot configuration issues is to increase the log level. To enable [trace log mode](https://docs.photoprism.app/getting-started/config-options/), set `PHOTOPRISM_LOG_LEVEL` to `"trace"` in the `environment:` section of the `photoprism` service (or use the `--trace` flag when running the `photoprism` command directly):
```yaml
services:
photoprism:
environment:
PHOTOPRISM_LOG_LEVEL: "trace"
...
```
Then [restart all services](https://docs.photoprism.app/getting-started/docker-compose/#step-2-start-the-server) for your changes to take effect:
```bash
docker compose stop
docker compose up -d
```
### Viewing Docker Service Logs
You can run this command to check the server logs for warnings and errors, including the last 100 messages (omit `--tail=100` to see them all, and `-f` to output only the last logs without watching them):
```bash
docker compose logs -f --tail=100
```
[Learn more ›](https://docs.photoprism.app/getting-started/troubleshooting/docker/#viewing-logs)
### Failed to Find Any PEM Data in Key Input
This error can indicate that your key file starts with an unexpected Byte Order Mark (BOM):
- https://www.google.com/search?q=failed+to+find+any+pem+data+tls+golang
- https://stackoverflow.com/questions/57596920/failed-to-find-any-pem-data-in-key
While BOMs are not strictly forbidden, there is only one way to encode UTF-8, and so they are not needed and extremely rare. As a result, a lot of software has problems with them.
You should be able to fix this by opening the file with a regular text or code editor (not Notepad) and then saving it again. Finally, restart all services for the changes to take effect:
```bash
docker compose stop
docker compose up -d
```
> [!NOTE]
> Our examples use the new `docker compose` command by default. If your server does not yet support it, you can still use `docker-compose` or alternatively `podman-compose` on Red Hat-compatible Linux distributions.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
[^1]: We may receive a credit when you sign up through our link, which helps us fund the project infrastructure.
---
# Volume Mounts
URL: https://www.photoprism.app/pro/kb/volumes/
> Get an overview of the folders used by PhotoPrism® Pro and learn how to mount network storage.
**When using Docker, all application services run in isolated containers, so you must explicitly [mount the host folders](https://docs.docker.com/reference/compose-file/services/#volumes) you want to use. Please note that PhotoPrism and MariaDB cannot see folders that have not been mounted. This is an important security feature.**
The following paths are used on the host if you are running Linux and follow our recommendation to install PhotoPrism in `/opt/photoprism`. In the Docker container, the `/opt` prefix is omitted so that, for example, `/opt/photoprism/originals` is mounted to `/photoprism/originals`:
## Originals Folder
The *originals* folder contains your original photo and video files. By default, it is located at `/opt/photoprism/originals` on the host server and at `/photoprism/originals` in the app container. If you are using Docker Compose, you can use `~` as a shortcut for the home directory.
```yaml
volumes:
- "./originals:/photoprism/originals" # original media files (photos and videos)
```
You can mount [any folder accessible from the host](https://docs.docker.com/reference/compose-file/services/#volumes), including network shares. Additional directories can also be mounted as subfolders of `/photoprism/originals` (depending on overlay file system support):
```yaml
volumes:
- "./originals:/photoprism/originals"
- "/mnt/photos:/photoprism/originals/media"
```
On Windows, prefix the host path with the drive letter and use `/` instead of `\` as separator:
```yaml
volumes:
- "D:/Originals:/photoprism/originals"
```
> [!NOTE]
> If *read-only mode* is enabled, all features that require write permission to the *originals* folder are disabled, e.g. [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/), uploading and deleting files. Set `PHOTOPRISM_READONLY` to `"true"` in `compose.yaml` for this. You can [mount a folder with the `:ro` flag](https://docs.docker.com/reference/compose-file/services/#volumes) to make Docker block write operations as well.
## Storage Folder
SQLite, config, cache, thumbnail, and sidecar files are saved in the *storage* folder, which by default is located at `/opt/photoprism/storage` on the host server and at `/photoprism/storage` in the app container.
- a *storage* folder mount must always be configured in your `compose.yaml` or `docker-compose.yml` file so that you do not lose these files after a restart or upgrade
- never configure the *storage* folder to be inside the *originals* folder unless the name starts with a `.` to indicate that it is hidden
- we recommend placing the *storage* folder on a [local SSD drive](/pro/kb/requirements/) for best performance
- mounting [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) or using them inside the *storage* folder is currently not supported
> [!NOTE]
> Should you later want to move your instance to another host, the easiest and most time-saving way is to copy the entire *storage* folder along with your originals and database.
## Import Folder
You can optionally mount an *import* folder from which files can be transferred to the *originals* folder in a structured way that avoids duplicates:
- by default, it is located at `/opt/photoprism/import` on the host server and at `/photoprism/import` in the app container
- [imported files](https://docs.photoprism.app/user-guide/library/import/) receive a canonical filename and will be organized by year and month
- never configure the *import* folder to be inside the *originals* folder, as this will cause a loop by importing already indexed files
> [!NOTE]
> You can safely skip this. Adding files via [Web Upload](https://docs.photoprism.app/user-guide/library/upload/) and [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/) remains possible, unless [read-only mode](/pro/kb/config-options/) is enabled or the [features have been disabled](https://docs.photoprism.app/user-guide/settings/general/).
## MariaDB Database
Our example includes a pre-configured [MariaDB](https://mariadb.com/) database server that uses `/opt/photoprism/database` as storage folder. If you remove it and provide no other database server credentials, SQLite database files will be created in `/opt/photoprism/storage`.
> [!NOTE]
> Never [store database files](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#corrupted-files) on an unreliable device such as a USB flash drive, SD card, or shared network folder. These may also have [unexpected file size limitations](https://thegeekpage.com/fix-the-file-size-exceeds-the-limit-allowed-and-cannot-be-saved/), which is especially problematic for databases that do not split data into smaller files. We strongly recommend using SSD storage for databases only, see [System Requirements](/pro/kb/requirements/)
## Network Storage
Shared folders that have already been mounted on your host can be mounted like any local drive or directory.
Alternatively, you can mount network storage with [Docker Compose](https://docs.docker.com/reference/compose-file/volumes/#driver_opts).
Please never store database files on an unreliable device such as a USB stick, SD card, or network drive.
### Unix / NFS
Follow this `compose.yaml` example to mount Network File System (NFS) shares e.g. from Unix servers or NAS devices:
```yaml
services:
photoprism:
# ...
volumes:
# Map named volume "originals"
# to "/photoprism/originals":
- "originals:/photoprism/originals"
mariadb:
# ...
# Specify named volumes:
volumes:
originals:
driver_opts:
type: nfs
# Authentication and other mounting options:
o: "addr=1.2.3.4,username=user,password=secret,soft,rw,nfsvers=4"
# Mount this path:
device: ":/mnt/example"
```
`device` should contain the path to the share on the NFS server, note the `:` at the beginning. In the above example, the share can be mounted as the named volume `originals`. You can also choose another name as long as it is consistent.
Driver-specific options can be set after the server address in `o`, see the [nfs manual page](https://man7.org/linux/man-pages/man5/nfs.5.html). Here are some examples of commonly used options:
- `nfsvers=3` or `nfsvers=4` to specify the NFS version
- `nolock` (optional): Remote applications on the NFS server are not affected by lock files inside the Docker container (only other processes inside the container are affected by locks)
- `timeo=n` (optional, default 600): The NFS client waits `n` tenths of a second before retrying an NFS request
- `soft` (optional): The NFS client aborts an NFS request after `retrans=n` unsuccessful retries, otherwise it retries indefinitely
- `retrans=n` (optional, default 2): Sets the number of retries for NFS requests, only relevant when using `soft`
### SMB / CIFS
Follow this `compose.yaml` example to mount [CIFS network shares](https://en.wikipedia.org/wiki/Server_Message_Block), e.g. **from Windows**, NAS devices or Linux servers with [Samba](https://www.samba.org/):
```yaml
services:
photoprism:
# ...
volumes:
# Map named volume "originals"
# to "/photoprism/originals":
- "originals:/photoprism/originals"
mariadb:
# ...
# Specify named volumes:
volumes:
originals:
driver_opts:
type: cifs
o: "username=user,password=secret,rw"
device: "//host/folder"
```
Then restart all services for the changes to take effect. Note that related values must start at the same indentation level [in YAML](https://docs.photoprism.app/developer-guide/technologies/yaml/) and that **tabs are not allowed for indentation**. We recommend using 2 spaces, but any number will do as long as it is consistent.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Pro Knowledge Base](/pro/kb/)
---
# Web Overlay
URL: https://www.photoprism.app/pro/kb/web-overlay/
> Learn how to publish a static landing page or branded entrypoint from the storage folder in PhotoPrism® Pro.
Starting with PhotoPrism® Pro Build `1.2603.05`, you can place static web content in the `storage/web` folder and serve it directly from the same public URL as your server or tenant path. This is useful for branded landing pages, welcome screens, help links, lightweight status pages, and other static assets that should live next to your deployment.
## How It Works
When a `storage/web` directory exists, PhotoPrism automatically checks it for matching files before returning the default login redirect or a `404` response:
- `/` serves `storage/web/index.html`
- `/about/` serves `storage/web/about/index.html`
- `/img/logo.svg` serves `storage/web/img/logo.svg`
This means you can structure your files like a small static website:
```text
storage/
web/
index.html
about/
index.html
css/
site.css
img/
logo.svg
```
If no `index.html` exists at the overlay root, requests to the server root continue to open the usual sign-in page instead.
## Typical Use Cases
- Show a branded landing page before users sign in
- Provide links to support, legal notices, or onboarding resources
- Publish a tenant-specific start page on a shared Portal domain
- Serve static assets for an external login or registration flow
The overlay is intended for static files only. Dynamic requests, uploads, and API calls continue to be handled by the normal PhotoPrism application routes.
## Shared Domains and Portal Routing
The overlay also works when instances are published below a path such as `https://portal.example.com/i/acme/`. In that case, your instance must use the same public base URL in its site configuration so that generated links, redirects, and browser storage remain isolated to the correct tenant path.
Examples:
- Root landing page: `https://portal.example.com/`
- Tenant landing page: `https://portal.example.com/i/acme/`
When a tenant path is used, the canonical public URL should include the trailing slash. Requests to `/i/acme` are redirected to `/i/acme/`, while deeper paths are forwarded as-is so that file access and WebDAV clients keep working correctly.
## Important Behavior
- Static files are served only for `GET` and `HEAD` requests
- Paths without a filename extension are resolved to `index.html` inside the requested folder
- Missing root content falls back to the normal login redirect
- Missing files below other paths return the standard `404` response
- Hidden files, unsafe paths, and common secret or configuration files are never served
In practice, this means you should keep only public web assets in `storage/web` and continue storing keys, certificates, backups, and configuration files elsewhere under `storage`.
## Recommendations
We recommend the following when using the web overlay in production:
- Keep your public server URL configured correctly, especially when using a reverse proxy or Portal tenant path
- Use [HTTPS](/pro/kb/https/) so landing pages, sign-in flows, and linked assets are delivered securely
- Keep the overlay small and focused on static content
- Use folder-based routes such as `/about/` and `/help/` if you want clean URLs
- Review [release notes](/pro/kb/release-notes/) before upgrading shared-domain deployments
## Related Resources
- [Quick Start](/pro/kb/quickstart/)
- [Config Options](/pro/kb/config-options/)
- [OpenID Connect](/pro/kb/openid-connect/)
- [Release Notes](/pro/kb/release-notes/)
---
# File Format Support
URL: https://www.photoprism.app/plus/kb/file-formats/
> Get an overview of the supported image, video and sidecar file types and their extensions.
| Format | Description | Type | Extensions |
|:-------|:-----------------------------------------------|:---------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ZIP | ZIP Archive File | Archive | .zip |
| PDF | Portable Document Format (PDF) | Document | .pdf |
| AVIF | AV1 Image File Format | Image | .avif |
| AVIFS | AV1 Image Sequence | Image | .avifs, .avis |
| BMP | Bitmap | Image | .bmp |
| GIF | Graphics Interchange Format | Image | .gif |
| HEIC | High Efficiency Image Container | Image | .avci, .avcs, .heic, .heif, .hif |
| HEICS | HEIC Image Sequence | Image | .heics, .heifs |
| JPG | Joint Photographic Experts Group (JPEG) | Image | .jfi, .jfif, .jif, .jpe, .jpeg, .jpg |
| JXL | JPEG XL | Image | .jxl |
| MPO | Stereoscopic JPEG (3D) | Image | .mpo |
| PNG | Portable Network Graphics | Image | .apng, .pn, .png, .pnga |
| PSD | Adobe Photoshop | Image | .psd |
| THM | Thumbnail Image | Image | .thm |
| TIFF | Tag Image File Format | Image | .tif, .tiff |
| WEBP | Google WebP | Image | .webp |
| DNG | Adobe Digital Negative | Raw | .dng |
| RAW | Unprocessed Sensor Data | Raw | .3fr, .ari, .arw, .bay, .cap, .cr2, .cr3, .crw, .data, .dcr, .dcs, .drf, .eip, .erf, .fff, .gpr, .iiq, .k25, .kdc, .mdc, .mef, .mos, .mrw, .nef, .nrw, .obm, .orf, .pef, .ptx, .pxn, .r3d, .raf, .raw, .rw2, .rwl, .rwz, .sr2, .srf, .srw, .x3f |
| AAE | Apple Image Edits XML | Sidecar | .aae |
| JSON | Serialized JSON Data (Exiftool, Google Photos) | Sidecar | .json |
| MD | Markdown Formatted Text | Sidecar | .markdown, .md |
| NFO | Info Text | Sidecar | .nfo |
| TXT | Plain Text | Sidecar | .txt |
| XML | Extensible Markup Language | Sidecar | .xml |
| XMP | Adobe Extensible Metadata Platform | Sidecar | .xmp |
| YML | Serialized YAML Data (Config, Metadata) | Sidecar | .yaml, .yml |
| AI | Adobe Illustrator | Vector | .ai |
| EPS | Encapsulated PostScript | Vector | .epi, .eps, .eps2, .eps3, .epsf, .epsi, .ept |
| PS | Adobe PostScript | Vector | .ps, .ps2, .ps3 |
| SVG | Scalable Vector Graphics | Vector | .svg |
| 3G2 | Mobile Multimedia Container (CDMA2000) | Video | .3g2 |
| 3GP | Mobile Multimedia Container (3G) | Video | .3gp |
| ASF | Advanced Systems Format | Video | .asf |
| AV1 | AOMedia Video 1 | Video | .av01, .av1 |
| AVC | Advanced Video Coding (H.264, MPEG-4 Part 10) | Video | .avc, .avc1, .avc10, .avc2, .avc3, .dva, .dva1, .dvav, .h264 |
| AVI | Microsoft Audio Video Interleave | Video | .avi |
| DV | DV Video | Video | .dv |
| EVC | Essential Video Coding (MPEG-5 Part 1) | Video | .evc, .evc1 |
| FLV | Adobe Flash | Video | .f4v, .flv |
| HEV | High Efficiency Video Coding (HEVC) Bitstream | Video | .dvhe, .hev, .hev1, .hev10, .hev2, .hev3 |
| HVC | High Efficiency Video Coding (H.265) | Video | .dvh, .dvh1, .h265, .hevc, .hevc10, .hvc, .hvc1, .hvc10, .hvc2, .hvc3 |
| M2T | MPEG-2 Transport Stream (M2TS) | Video | .m2t, .m2ts, .mp2t, .ts |
| M4V | Apple iTunes Multimedia Container | Video | .m4v |
| MJPG | Motion JPEG | Video | .mjpeg, .mjpg |
| MKV | Matroska Multimedia Container | Video | .mkv |
| MOV | Apple QuickTime | Video | .mov, .qt |
| MP2 | MPEG 2 (H.262) | Video | .mp2, .mpv |
| MP4 | Multimedia Container (MPEG-4 Part 14) | Video | .mp, .mp4 |
| MPG | Moving Picture Experts Group (MPEG) | Video | .mpeg, .mpg |
| MTS | Advanced Video Coding High Definition (AVCHD) | Video | .mts |
| MXF | Material Exchange Format | Video | .mxf |
| OGV | Ogg Media (OGG) | Video | .ogg, .ogv, .ogx |
| VP8 | Google VP8 Video | Video | .vp8 |
| VP9 | Google VP9 Video | Video | .vp9 |
| VVC | Versatile Video Coding (H.266) | Video | .h266, .vvc, .vvc1 |
| WEBM | Google WebM | Video | .webm |
| WMV | Windows Media | Video | .wmv |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Getting Updates
URL: https://www.photoprism.app/plus/kb/updates/
> This guide shows you how to get and install updated versions of PhotoPrism® Plus.
### Docker Compose
Open a terminal and change to the folder where your `compose.yaml` or `docker-compose.yml` file is located.[^1] Now run the following commands to download the [most recent version](https://docs.photoprism.app/release-notes/) from our private registry and restart your instance in the background:[^2]
```
docker compose up -d --pull always
```
Pulling a new version can take several minutes, depending on your internet connection speed. Advanced users can [add this to a `Makefile`](https://dl.photoprism.app/docker/Makefile) so that they only have to type a single command like `make update`.
> [!NOTE]
> Even when you use an image with the `:latest` tag, Docker does not automatically download new images for you. You can either manually upgrade as shown above, or set up a service like [Watchtower](#watchtower) to get automatic updates.
#### Config Examples
We recommend that you compare your own `compose.yaml` with [our latest examples](/plus/kb/quickstart/#step-1) from time to time, as they may include new [config options](/plus/kb/config-options/) or other enhancements relevant to you.
#### Development Preview
You can test upcoming features and enhancements by changing the image from `photoprism/photoprism:latest` to `photoprism/photoprism:preview` in your [`compose.yaml`](https://dl.photoprism.app/docker/). Then pull the most recent image and restart your instance as shown above.
#### Watchtower
Adding [Watchtower](https://github.com/nicholas-fedor/watchtower) as a service to your `compose.yaml` will automatically keep images up-to-date:
```yaml
services:
watchtower:
image: nickfedor/watchtower
restart: unless-stopped
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
```
> [!NOTE]
> Automatic updates may interrupt indexing and import operations. Only enable Watchtower if you are comfortable with this.
### Pure Docker
Open a terminal on your server, and run the following command to pull the most recent container image:[^2]
```
docker pull photoprism/photoprism:latest
```
### Complete Rescan
We recommend performing a [complete rescan](https://docs.photoprism.app/user-guide/library/originals/#when-should-complete-rescan-be-selected) after major updates to take advantage of new search filters and sorting options. Be sure to [read the notes for each release](https://docs.photoprism.app/release-notes/) to see what changes have been made and if they might affect your library, for example, because of the file types you have or because new search features have been added. If you encounter problems that you cannot solve otherwise (i.e. before reporting a bug), please also try a rescan and see if it solves the problem.
You can start a [rescan from the user interface](https://docs.photoprism.app/user-guide/library/originals/) by navigating to *Library* > *Index*, selecting "Complete Rescan", and then clicking "Start". Manually entered information such as labels, people, titles or descriptions will not be modified when indexing, even if you perform a "complete rescan".
> [!NOTE]
> Be careful not to start multiple indexing processes at the same time, as this will lead to a high server load.
### MariaDB Server
Our [configuration examples](/plus/kb/quickstart/#step-1) are generally based on the [current stable version](https://mariadb.com/kb/en/mariadb-server-release-dates/) to take advantage of performance improvements. This does not mean that [older versions](https://docs.photoprism.app/getting-started/#databases) are no longer supported and you must upgrade immediately. We recommend not using the `:latest` tag for the MariaDB Docker image and to upgrade manually by changing the tag once we had a chance to test a new major version, e.g.:
```yaml
services:
mariadb:
image: mariadb:12.3
...
```
If MariaDB fails to start after upgrading from an earlier version (or migrating from MySQL), the internal management schema may be outdated. See [Troubleshooting MariaDB Problems](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#version-upgrade) for instructions on how to fix this.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
[^1]: The default [Docker Compose](https://docs.docker.com/compose/) config filename is `compose.yaml`. For simplicity, it doesn't need to be specified when running `docker compose` in the same directory. Config files for other apps or instances should be placed in separate folders.
[^2]: Our guides use the new `docker compose` command by default. If your server does not yet support it, the old `docker-compose` command will still work. Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the `docker` and `docker compose` commands with `podman` and `podman-compose` as drop-in replacements.
---
# Metadata Compatibility
URL: https://www.photoprism.app/plus/kb/metadata/
> Get an overview of the supported Exif, XMP, IPTC, and DCMI tags and their internal field names.
| Field | Type | Exiftool | Adobe XMP | DCMI |
|:--------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------|:-----------------|
| Altitude | decimal | GlobalAltitude, GPSAltitude | | |
| Aperture | decimal | ApertureValue, Aperture | | |
| FNumber | decimal | FNumber | | |
| FPS | decimal | VideoFrameRate, VideoAvgFrameRate | | |
| FocalDistance | decimal | HyperfocalDistance | | |
| Duration | duration | Duration, MediaDuration, TrackDuration, PreviewDuration | | |
| Favorite | flag | Favorite | | |
| Flash | flag | FlashFired | | |
| Keywords | list | Keywords | | |
| FocalLength | number | FocalLength, FocalLengthIn35mmFormat | | |
| Frames | number | FrameCount, AnimationFrames | | |
| Height | number | ImageHeight, ImageLength, PixelYDimension, ExifImageHeight, SourceImageHeight | | |
| ImageType | number | HDRImageType | | |
| Iso | number | ISO | | |
| Pages | number | PageCount, NPages, Pages | | |
| Rotation | number | Rotation | | |
| Width | number | ImageWidth, PixelXDimension, ExifImageWidth, SourceImageWidth | | |
| Artist | text | Artist, Creator, By-line, OwnerName, Owner | Creator | |
| CameraMake | text | CameraMake, Make | Make | |
| CameraModel | text | CameraModel, Model, CameraID, UniqueCameraModel | CameraModel, Model | |
| CameraOwner | text | OwnerName | | |
| CameraSerial | text | SerialNumber | | |
| Caption | text | Description, ImageDescription, Caption, Caption-Abstract | Description, Description.Alt | |
| Codec | text | CompressorID, VideoCodecID, CodecID, OtherFormat, FileType | | |
| ColorProfile | text | ICCProfileName, ProfileDescription | | |
| Copyright | text | Rights, Copyright, CopyrightNotice, WebStatement | Rights, Rights.Alt | |
| DocumentID | text | ContentIdentifier, MediaGroupUUID, BurstUUID, OriginalDocumentID, DocumentID, ImageUniqueID, DigitalImageGUID | | |
| Exposure | text | ExposureTime, ShutterSpeedValue, ShutterSpeed, TargetExposureTime | | |
| FileName | text | FileName | | |
| GPSLatitude | text | GPSLatitude | | |
| GPSLongitude | text | GPSLongitude | | |
| GPSPosition | text | GPSPosition | | |
| InstanceID | text | InstanceID, DocumentID | | |
| LensMake | text | LensMake | | |
| LensModel | text | LensModel, Lens, LensID | LensModel, Lens | |
| License | text | UsageTerms, License | | |
| Notes | text | Comment, UserComment | | |
| Projection | text | ProjectionType | | |
| Software | text | Software, Producer, CreatorTool, Creator, CreatorSubTool, HistorySoftwareAgent, ProcessingSoftware | | |
| Subject | text | Subject, PersonInImage, ObjectName, HierarchicalSubject, CatalogSets | Subject | |
| TimeOffset | text | OffsetTime, OffsetTimeOriginal, OffsetTimeDigitized | | |
| Title | text | Title, Headline | dc:title | title, title.Alt |
| CreatedAt | timestamp | SubSecCreateDate, CreationTime, CreationDate, CreateDate, MediaCreateDate, ContentCreateDate, TrackCreateDate | | |
| TakenAt | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationTime, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | DateCreated, CreationTime | |
| TakenAtLocal | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | | |
| TakenGps | timestamp | GPSDateTime, GPSDateStamp | | |
## Metadata Tags by Namespace ##
| Namespace | Documentation |
|---------------------|----------------------------------------------------------------------|
| Exiftool Exif | https://exiftool.sourceforge.net/TagNames/EXIF.html |
| Exiftool XMP | https://exiftool.sourceforge.net/TagNames/XMP.html |
| Adobe XMP | https://docs.photoprism.app/developer-guide/metadata/xmp/#references |
| Dublin Core (DCMI) | https://www.dublincore.org/specifications/dublin-core/dcmi-terms/ |
| IPTC Photo Metadata | https://iptc.org/standards/photo-metadata/iptc-standard/ |
> [!NOTE]
> Original media and sidecar files are scanned for Exif and XMP data, as well as proprietary metadata, including Google Photos JSON. The combined information is then normalized, merged, and enriched with additional information.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Quickstart Guide
URL: https://www.photoprism.app/plus/kb/quickstart/
> In this guide, we show you how to set up PhotoPrism® Plus in just a few steps and customize it to your needs.
## System Requirements ##
We recommend hosting PhotoPrism® on a server with **at least 2 cores**, **4 GB of physical memory**, and a 64-bit operating system. It runs best with Docker Desktop on [Windows 10+](https://docs.docker.com/desktop/setup/install/windows-install/) and [macOS 11+](https://docs.docker.com/desktop/setup/install/mac-install/), [Podman](https://podman.io/) on Red Hat and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux, and [Docker](https://docs.docker.com/desktop/setup/install/linux/) on all other Linux distributions such as Ubuntu and Debian.
## Setup Using Docker Compose
[Docker Compose](https://docs.docker.com/compose/) uses a [human-friendly YAML config file](https://docs.photoprism.app/developer-guide/technologies/yaml/) to specify all application services, so you can easily start them with a single command.
For this to work, make sure that you have [Docker and Docker Compose](https://docs.photoprism.app/getting-started/troubleshooting/docker/#installation) (Linux) or [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows) installed and running on your server before you continue. If your server does not yet support the new `docker compose` command, you can still use the legacy `docker-compose` command instead.
**Windows** users should have the latest [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) installed. With Windows Pro, Server and Enterprise, [Hyper-V can be enabled](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) as an alternative, which Microsoft does not offer its Windows Home customers.
**Linux Kernel Security Modules** such as AppArmor and SELinux may [require additional configuration](https://docs.photoprism.app/getting-started/troubleshooting/docker/#kernel-security) if you want to use them. The application services may fail to start if they have insufficient permissions or privileges.
In case you are not sure if you have Docker installed yet, and if so, which version, you can run the following command in a terminal to display the version information:
```
docker --version
```
> [!NOTE]
> Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the `docker` and `docker compose` commands with `podman` and `podman-compose` as [drop-in replacements](https://docs.photoprism.app/getting-started/troubleshooting/docker/#podman-compose).
### Step 1: Customize Configuration ###
Download the *compose.yaml* default configuration for your operating system (right click and *Save Link As...*) to a local folder, e.g. `/opt/photoprism` on Linux, then open the file with a text editor to [customize the storage volumes](/plus/kb/volumes/) and [other options](/plus/kb/config-options/) as needed:
| | |
|-------------|----------------------------------------------------------------------------------------------------------------|
| **Linux** | [https://dl.photoprism.app/docker/compose.yaml](https://dl.photoprism.app/docker/compose.yaml) |
| **Windows** | [https://dl.photoprism.app/docker/windows/compose.yaml](https://dl.photoprism.app/docker/windows/compose.yaml) |
| **macOS** | [https://dl.photoprism.app/docker/macos/compose.yaml](https://dl.photoprism.app/docker/macos/compose.yaml) |
Please refer to our [official documentation](https://docs.photoprism.app/) for [basic settings](https://docs.photoprism.app/getting-started/docker-compose/#volumes) and [general setup instructions](https://docs.photoprism.app/getting-started/docker-compose/). When editing the configuration file, related values must start at the same indentation level [in YAML files](https://docs.photoprism.app/developer-guide/technologies/yaml/) and that tabs are not allowed for indentation. We recommend using 2 spaces.
Please always change `PHOTOPRISM_ADMIN_PASSWORD` so that the app starts with a secure initial password. Never use easy-to-guess passwords or default values like "insecure" on publicly accessible servers. There is no default in case no password was provided. A minimum length of 8 characters is required.
### Step 2: Start PhotoPrism ###
When you are done with the configuration, open a terminal and change to the folder where the *compose.yaml* file was saved.
Now run the following commands to pull the latest image from there, and then start MariaDB and PhotoPrism as background services:
```
docker compose pull
docker compose up -d
```
After waiting a few moments, you should be able to open the user interface in a Web browser by navigating to:
👉 [**http://localhost:2342/**](http://localhost:2342/)
If you have modified the server hostname, port, or protocol in your configuration, the URL to use changes accordingly.
Other issues? Our [Troubleshooting Checklists](https://docs.photoprism.app/getting-started/troubleshooting/) help you quickly diagnose and solve them.
When you see the login screen, **sign in with the admin username and initial password** you specified in your *compose.yaml* file.
You can change it in the user interface when you navigate to *Settings > Account*. PhotoPrism® Plus also includes a [web user interface for creating additional accounts](https://docs.photoprism.app/user-guide/users/) and managing sessions.
> [!NOTE]
> Note that the examples in our documentation use the new `docker compose` command by default. If your server does not yet support it, the old `docker-compose` command will continue to work.
> [!NOTE]
> To verify that all services are running properly, you can view the server logs at any time by running `docker compose logs -f`.
### Step 3: Index Your Library & Create Accounts ###
Our [First Steps 👣](https://docs.photoprism.app/user-guide/first-steps/) tutorial guides you through the user interface and library settings to ensure your library is indexed according to your individual preferences.
In the following section, we'll give you an overview of the additional features available in PhotoPrism® Plus.
## User Management ##
PhotoPrism® Plus includes advanced multi-user functionality with additional account roles. These roles are intended for applications where multiple users share a single library or, for example, to give family members access to your personal library without granting write permissions or exposing private content.
It is recommended that you set up multiple instances of PhotoPrism® Plus if you have multiple users, such as a family, who want to manage their own files independently and share only selected content. That way you can avoid problems with conflicting library settings, file permissions, and dealing with duplicates.
## Session Monitoring
Built-in reporting helps you monitor PhotoPrism® Plus for potential vulnerabilities, misuse, and other critical incidents.
## Using HTTPS
Our guide shows you how to enable transport encryption, add server certificates, and create new certificates.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Search Filter Reference
URL: https://www.photoprism.app/plus/kb/search-filters/
> Get an overview of the supported search filters and learn how to use them.
| Filter | Type | Examples | Notes |
|:------------|:----------|:--------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| dist | decimal | dist:50 | Maximum distance to position in km |
| lat | decimal | lat:41.894043 | Position latitude (-90.0 to 90.0 deg) |
| lng | decimal | lng:-87.62448 | Position longitude (-180.0 to 180.0 deg) |
| chroma | number | chroma:70 | Chroma (0-100) |
| diff | number | diff:-1 diff:2 | Differential Perceptual Hash (000000-FFFFFF) |
| quality | number | quality:0 quality:3 | Minimum quality score (1-7) |
| album | string | album:berlin | Album UID or name, supports * wildcards |
| albums | string | albums:"South Africa & Birds" | Album names, combinable with & or \| |
| alt | string | alt:300-500 | Altitude (m) |
| camera | string | camera:canon | Camera make or model |
| caption | string | caption:"Lake*" | Searches text in captions separated by \|, or specify false to find content without a caption |
| category | string | category:airport | Location category type |
| city | string | city:"Berlin" | City names, separated by \| |
| codec | string | codec:avc1 | Media codec types separated by \|, e.g. jpeg, avc1, or hvc1 |
| color | string | color:"red\|blue" | Color name separated by \|, e.g. purple, magenta, pink, red, orange, gold, yellow, lime, green, teal, cyan, blue, brown, white, grey, or black |
| country | string | country:"de\|us" | Country codes, separated by \| |
| day | string | day:3\|13 | Days 1-31, separated by \| |
| description | string | description:"Lake*" | Searches text in titles or captions separated by \|, or specify false to find content without a title or caption |
| f | string | f:2.8-4.5 | Aperture (F-Number) |
| face | string | face:PN6QO5INYTUSAATOFL43LL2ABAV5ACZG | Find pictures with a specific face ID, you can also specify yes, no, new, or a face type |
| faces | string | faces:yes faces:3 | Minimum number of detected faces (yes means 1) |
| favorite | string | favorite:true favorite:false | Finds favorite content |
| filename | string | filename:"2021/07/12345.jpg" | File names including path and extension, separated by \| |
| folder | string | folder:"*/2020" | Alias for the path filter |
| geo | string | geo:yes | Finds content with or without latitude and longitude |
| hash | string | hash:2fd4e1c67a2d | SHA1 file hashes, separated by \| |
| id | string | id:123e4567-e89b-... | Finds content with the specified Image, Document or Instance IDs, separated by \| |
| iso | string | iso:200-400 | ISO number (light sensitivity) |
| keywords | string | keywords:"sand&water" | Keywords, combinable with & and \| |
| label | string | label:"cat\|dog&!blurry" | Label names: \| is OR within a group, & is AND between groups (every positive group must match), leading ! negates a group (e.g. !rejected). Category expansion applies to both positive and negative terms. Escape a literal &, \|, or leading ! with \ |
| latlng | string | latlng:49.4,13.41,46.5,2.331 | Position bounding box (Lat N, Lng E, Lat S, Lng W) |
| lens | string | lens:ef24 | Lens make or model |
| mm | string | mm:28-35 | Focal length (35mm equivalent) |
| month | string | month:7\|10 | Months from 1-12, separated by \| |
| mp | string | mp:3-6 | Resolution in Megapixels (MP) |
| name | string | name:"IMG_9831-112*" | File names without path and extension, separated by \| |
| near | string | near:pqbcf5j446s0futy | Finds nearby pictures (UID) |
| olc | string | olc:8FWCHX7W+ | Open Location Code (OLC) |
| original | string | original:"IMG_9831-112*" | Original file names of imported files, separated by \| |
| path | string | path:2020/Holiday | Path names separated by \|, supports * wildcards |
| people | string | people:"Jane & John" | Subject names, combinable with & or \| |
| person | string | person:"Jane Doe & John Doe" | Subject names, will be matched exactly and can be combined using & or \| |
| s2 | string | s2:4799e370ca54c8b9 | Position, specified as S2 Cell ID |
| scan | string | scan:true scan:false | Finds scanned photos and documents |
| state | string | state:"Baden-Württemberg" | State or province names, separated by \| |
| subject | string | subject:"Jane Doe & John Doe" | Alias for person |
| subjects | string | subjects:"Jane & John" | Alias for people |
| title | string | title:"Lake*" | Searches text in titles separated by \|, or specify false to find content without a title |
| type | string | type:image\|raw\|live | Finds specific media types, such as image, raw, live, video, animated, audio, vector, or document, separated by \| |
| uid | string | uid:pqbcf5j446s0futy | Finds content with the specified internal UIDs, separated by \| |
| year | string | year:1990\|2003 | Years, separated by \| |
| animated | switch | animated:yes | Finds animated images only |
| archived | switch | archived:yes | Finds archived content |
| audio | switch | audio:yes | Finds audio content only |
| document | switch | document:yes | Finds PDF documents only |
| error | switch | error:yes | Finds content with errors |
| hidden | switch | hidden:yes | Finds hidden content (broken or unsupported) |
| image | switch | image:yes | Finds regular photos and images only |
| landscape | switch | landscape:yes | Finds landscape pictures only |
| live | switch | live:yes | Finds Motion and Live Photos only |
| media | switch | media:yes | Finds live, video, audio, and animated content only |
| mono | switch | mono:yes | Pictures with few or no colors |
| panorama | switch | panorama:yes | Finds panorama pictures only (aspect ratio 1.9:1 or more) |
| photo | switch | photo:yes | Finds regular photos and images, as well as RAW and Live Photos |
| portrait | switch | portrait:yes | Finds portrait pictures only |
| primary | switch | primary:yes | Finds primary JPEG or PNG files only |
| private | switch | private:yes | Finds private content only (except when public:true) |
| public | switch | public:yes | Excludes private content |
| raw | switch | raw:yes | Finds RAW images only |
| review | switch | review:yes | Finds content in review |
| square | switch | square:yes | Finds square pictures only (aspect ratio 1:1) |
| stack | switch | stack:yes | Finds content with more than one media file |
| stackable | switch | stackable:yes | Finds content that can be stacked with additional files |
| unsorted | switch | unsorted:yes | Finds content that is not in an album |
| unstacked | switch | unstacked:yes | Finds content with a file that has been removed |
| vector | switch | vector:yes | Finds vector graphics only |
| video | switch | video:yes | Finds video content only |
| added | timestamp | added:"2006-01-02T15:04:05Z" | Finds content added at or after this time |
| after | timestamp | after:"2022-01-30" | Finds content created on or after this date |
| before | timestamp | before:"2022-01-30" | Finds content created before this date |
| edited | timestamp | edited:"2006-01-02T15:04:05Z" | Finds content edited at or after this time |
| taken | timestamp | taken:"2022-01-30" | Finds content created on the specified date |
| updated | timestamp | updated:"2006-01-02T15:04:05Z" | Finds content updated at or after this time |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Security Options
URL: https://www.photoprism.app/plus/kb/security/
> Get an overview of the additional security features and config options available to our members.
PhotoPrism® Plus includes the following additional config options, as well as more secure default settings to protect your instance by blocking vulnerability scanners and preventing the exploitation of newly discovered issues:
| Environment | CLI Flag | Default | Description |
|---------------------------------|------------------------|---------------|---------------------------------------------------------------------------------------------------------|
| PHOTOPRISM_STS_SECONDS | --sts-seconds | 31536000 | `TIME` for the browser to remember that the site is to be accessed only via HTTPS (0 to disable) *plus* |
| PHOTOPRISM_STS_SUBDOMAINS | --sts-subdomains | | rule applies to all subdomains as well *plus* |
| PHOTOPRISM_STS_PRELOAD | --sts-preload | | submit to Google's HSTS preload service *plus* |
| PHOTOPRISM_LOGIN_LIMIT | --login-limit | 10 | maximum number of consecutive failed LOGIN `ATTEMPTS` from a single IP *plus* |
| PHOTOPRISM_LOGIN_INTERVAL | --login-interval | 1m0s | average `DURATION` between failed LOGIN attempts from a single IP (0-86400s) *plus* |
| PHOTOPRISM_IPS_LIMIT | --ips-limit | 3 | maximum number of malicious request `ATTEMPTS` before a client IP is blocked (-1 to disable) *plus* |
| PHOTOPRISM_IPS_INTERVAL | --ips-interval | 1h0m0s | average `DURATION` between malicious request attempts from a single IP (0-86400s) *plus* |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_CTO | --http-cto | nosniff | HTTP X-Content-Type-Options `HEADER` *plus* |
| PHOTOPRISM_HTTP_COOP | --http-coop | same-origin | HTTP Cross-Origin-Opener-Policy (COOP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_REFERRER_POLICY | --http-referrer-policy | same-origin | HTTP Referrer-Policy `HEADER` *plus* |
| PHOTOPRISM_HTTP_FRAME_OPTIONS | --http-frame-options | DENY | HTTP X-Frame-Options `HEADER` *plus* |
| PHOTOPRISM_HTTP_XSS_PROTECTION | --http-xss-protection | 1; mode=block | HTTP X-XSS-Protection `HEADER` *plus* |
| PHOTOPRISM_HTTP_HOSTNAME | --http-hostname | | serve requests for this `HOSTNAME` only *plus* |
## Using a Reverse Proxy
Providing these additional config options is a special service we offer to our members. However, advanced users can set the same web security headers in combination with [a reverse proxy running in front of their instances](https://docs.photoprism.app/getting-started/proxies/traefik/) if they did not sign up for a membership or have special requirements.
> [!NOTE]
> Should you decide to use alternative solutions, such as deploying a proxy or a web application firewall (WAF) in front of PhotoPrism, please note that our team will not be able to provide you with technical support and we recommend this only if you have the experience required.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Session Monitoring
URL: https://www.photoprism.app/plus/kb/monitoring/
> Built-in reporting helps you monitor PhotoPrism® Plus for potential vulnerabilities, misuse, and other critical incidents.
## Viewing Login Attempts
For security reasons, authentication logs are not visible on the regular web user interface and can only be viewed in the application service logs or searched in a terminal using the following CLI command:
```
photoprism logins ls [search]
```
### Command Options
You can combine it with these flags to change the output format and the maximum number of search results:
| Command Flag | Description |
|--------------|----------------------------------------|
| `--md, -m ` | format as machine-readable Markdown |
| `--csv, -c` | export as semicolon separated values |
| `--tsv, -t` | export as tab separated values |
| `-n LIMIT` | LIMIT number of results (default: 100) |
### Example Report
| Client IP | User Name | Realm | Status | Last Login | Failed At |
|------------|-----------|-------|--------|---------------------|-----------|
| 172.19.0.1 | user | api | OK | 2023-02-03 07:17:46 | |
| 172.19.0.1 | viewer | api | OK | 2023-02-03 07:16:55 | |
| 172.19.0.1 | admin | api | OK | 2023-02-03 06:55:06 | |
> [!NOTE]
> Run `photoprism logins clear` to clear all recorded incidents and reset the database to a clean state.
## Session Management
You can use the following terminal commands to create, inspect and, if necessary, delete access tokens for the authentication of browsers and other clients (including [app passwords](https://docs.photoprism.app/user-guide/settings/account/#apps-and-devices)):
| CLI Command | Description |
|-------------------------------------|----------------------------------------------------------|
| `photoprism auth ls [search]` | Lists currently authenticated users and clients |
| `photoprism auth add [username]` | Adds a new authentication secret for client applications |
| `photoprism auth show [identifier]` | Shows detailed information about a session |
| `photoprism auth rm [identifier]` | Deletes a session by id or access token |
| `photoprism auth reset --yes` | Resets the authentication of all users and clients |
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# System Requirements
URL: https://www.photoprism.app/plus/kb/requirements/
> PhotoPrism® Plus Hard- and Software Compatibility
**We recommend hosting PhotoPrism® Plus on a server with at least 2 cores, 4 GB of physical memory, and a 64-bit operating system. Beyond these minimum requirements, the amount of RAM should [match the number of CPU cores](https://docs.photoprism.app/getting-started/troubleshooting/performance/#memory). Indexing large photo and video collections also benefits greatly from [local SSD storage](https://docs.photoprism.app/getting-started/troubleshooting/performance/#storage), especially for the database and cache files.**
## Operating Systems
PhotoPrism® Plus runs best with Docker Desktop on [Windows 10+](https://docs.docker.com/desktop/setup/install/windows-install/) and [macOS 11+](https://docs.docker.com/desktop/setup/install/mac-install/), [Podman](https://podman.io/) on Red Hat and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux, and [Docker](https://docs.docker.com/desktop/setup/install/linux/) on all other Linux distributions such as Ubuntu and Debian.
Our multi-arch Docker image supports 64-bit AMD, Intel and ARM processors. As a result, [Raspberry Pi 3 / 4](https://docs.photoprism.app/getting-started/raspberry-pi/), Apple Silicon and other ARM64-based devices can pull from the same repository, enjoy the exact same functionality and follow the regular installation instructions.
## Databases
PhotoPrism is compatible with [SQLite 3](https://www.sqlite.org/) and [MariaDB 10.5.12+](https://mariadb.org/). The configuration examples we provide are generally based on the latest [MariaDB Server](https://mariadb.com/kb/en/mariadb-server-release-dates/) version to take advantage of performance improvements. We recommend [using SQLite only for small libraries](https://docs.photoprism.app/getting-started/troubleshooting/sqlite/) and test environments where scalability and performance are not important. Also note that [support for MySQL 8 has been discontinued](https://github.com/photoprism/photoprism/issues/1764) due to low demand and missing features.
## Browsers
Built as a [Progressive Web App](https://docs.photoprism.app/user-guide/pwa/) (PWA), the web interface works with most modern browsers and runs best on [Chrome](https://www.google.com/chrome/), [Chromium](https://www.chromium.org/getting-involved/download-chromium), [Safari](https://www.apple.com/safari/), [Firefox](https://www.mozilla.org/en-US/firefox/all/#product-desktop-release), and [Edge](https://www.microsoft.com/en-us/edge). You can conveniently install it on the home screen of all major operating systems and mobile devices.
Not all video and audio formats can be [played with every browser](https://docs.photoprism.app/getting-started/troubleshooting/browsers/). For example, [AAC](https://caniuse.com/aac "Advanced Audio Coding") - the default audio codec for [MPEG-4 AVC / H.264](https://caniuse.com/avc "Advanced Video Coding") - is supported natively in Chrome, Safari, and Edge, while it is only optionally supported by the OS in Firefox and Opera.
## Server CPU
Because PhotoPrism is designed to scale and make maximum use of the hardware provided, hosting it on a server with a more powerful CPU (or allocating more virtual cores) can make a big difference, especially when handling many concurrent requests or indexing large numbers of files. Ultimately, the choice of hardware should depend on your performance expectations and economic considerations.
#### NAS Devices
Entry-level NAS devices may not be suitable for running PhotoPrism® Plus, especially if the CPU is optimized for low power consumption.
We recommend testing the performance with our freely available [Community Edition](/editions/#compare).
## Memory ##
Indexing large photo and video collections benefits from plenty of memory for [caching](https://docs.photoprism.app/getting-started/troubleshooting/performance/#mariadb) and processing large media files. Ideally, the amount of RAM should match the number of physical CPU cores. If not, reduce the number of workers by setting `PHOTOPRISM_WORKERS` to a reasonably small value in `compose.yaml`, depending on the CPU performance and number of cores.
Especially the conversion of RAW images and the transcoding of videos are very demanding. High-resolution panoramic images may require [additional swap space](https://docs.photoprism.app/getting-started/troubleshooting/docker/#adding-swap) and/or physical memory above the recommended minimum.
> [!NOTE]
> RAW image conversion and TensorFlow are disabled on systems with 1 GB or less memory. We take no responsibility for instability or performance problems if your device does not meet the requirements.
#### Swap Space
If your server has [less than 4 GB of swap space](https://docs.photoprism.app/getting-started/troubleshooting/docker/#adding-swap) or a manual memory/swap limit is set, this can cause unexpected restarts, for example, when the indexer temporarily needs more memory to process large files.
## Storage
#### Disk Usage
Actual storage requirements vary and depend, among other things, on file resolutions and formats (RAW, JPEG, video,...). For highly compressed, high-resolution videos in modern formats that cannot be displayed natively by browsers, the *storage* folder may even be larger than the *originals* folder, since [videos transcoded to AVC](https://docs.photoprism.app/user-guide/organize/video/#transcoding) are not as heavily compressed. However, most of the space in the *storage* folder is usually occupied by thumbnails: These are high-quality, scaled-down versions of your originals.
Thumbnails are necessary because web browsers are bad at resizing large images to fit the screen. Using full-resolution originals for slideshows and in search results would also consume a lot of browser memory and significantly reduce indexing performance.
To reduce disk usage, you can [choose to render certain thumbnails only on demand](https://docs.photoprism.app/user-guide/settings/advanced/#preview-images) if you have a fast CPU and enough memory. On the other hand, if storage space is cheap, it can make more sense to go for better quality and performance.
> [!NOTE]
> We recommend that you **reserve about 50%** of the size of your *originals* for the *storage* folder so that you don't run out of space unexpectedly. Actual disk usage should be 25% or less in practice, depending on your individual quality settings and file types.
#### IOPS Constraints
There are no hard limits for the input and output operations per second (IOPS) that your hard drives should be able to perform. As a rule of thumb, a good M.2 SSD can easily do 100,000 IOPS or more, while conventional hard drives are between 50 and 100. For this reason, we strongly recommend using an SSD for MariaDB and the *storage* folder, which contains the configuration, thumbnail, cache and generated sidecar files.
Shared network storage or conventional hard drives should only be used for the *originals* folder. Performance is much less critical in this case, as these files are only accessed when indexing, downloading originals, or streaming videos. The number of concurrent reads depends on the number of cores available for indexing, so throughput is generally more important than IOPS. Thus, a conventional hard disk with 50 to 100 IOPS is sufficient unless you use a very large number of CPU cores for indexing.
> [!NOTE]
> Never store database files on an unreliable device such as a USB flash drive, SD card, or shared network folder. These may also have unexpected file size limitations, which is especially problematic for databases that do not split data into smaller files.
## Supported File Formats
PhotoPrism® Plus supports indexing, viewing, and converting most popular image, video and RAW formats, including JPEG, PNG, GIF, BMP, HEIF, HEIC, MP4, MOV, WebP, and WebM. Our goal is to provide top-notch support for all RAW images, regardless of camera make and model.
## Video Transcoding
For maximum browser compatibility, PhotoPrism can transcode video codecs and containers [supported by FFmpeg](https://www.ffmpeg.org/documentation.html) to [MPEG-4 AVC](https://en.wikipedia.org/wiki/MPEG-4), as well as extract still images for thumbnail creation. AVC, OGV, VP8, VP9, AV1, WebM, and HEVC videos can be streamed directly if they are supported by your browser and do not exceed the [configured bitrate limit](https://docs.photoprism.app/getting-started/advanced/transcoding/#bitrate-limit).
Our [dedicated configuration guide](https://docs.photoprism.app/getting-started/advanced/transcoding/) explains how to configure *Intel Quick Sync*, the *NVIDIA Container Toolkit* and other hardware encoders for accelerated hardware transcoding. Note that older hardware may not support certain video codecs and resolutions. In this case, it is not possible to use hardware transcoding for these videos.
## Concurrent Users
There is no predefined technical limit to the number of concurrent users. PhotoPrism generally scales well with the number of CPU cores, but keep in mind that the available server resources can be significantly reduced when the backend is busy indexing or importing a large number of files.
To reduce the server load, you can limit the number of indexing workers depending on your individual needs. It is also possible to change the file size limit in megabytes and the resolution limit in megapixels.
If you plan to connect your instance to the public Internet, where the number of users can fluctuate greatly and some users may be accessing the service from remote locations with high latency, we additionally recommend configuring a *Content Delivery Network (CDN)* like [bunny.net](https://link.photoprism.app/bunny-cdn), as this can effectively reduce server load and improve the user experience:
We recommend testing the performance with our freely available [Community Edition](/editions/#compare).
## Firewall
In order to successfully set up your installation and view location details in PhotoPrism® Plus, you must **allow requests to Docker Hub and our geocoding API** if you have a firewall installed, and make sure your internet connection is working.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Using a Content Delivery Network
URL: https://www.photoprism.app/plus/kb/using-a-cdn/
> Configuring a CDN can effectively reduce server load and improve user experience.
A *Content Delivery Network* is a distributed network of servers that can deliver static content to users around the world.
## When to use a CDN?
**Large Media Files:** PhotoPrism stores photos and videos that can be very large. A CDN can help speed up the delivery of these files to users.
**Global Audience:** If your PhotoPrism instance is accessed from different locations around the world, a CDN can help reduce latency and improve the overall user experience by delivering content from servers that are closer to your users.
**Many Users:** If your PhotoPrism instance is getting a lot of traffic, a CDN can improve application performance by reducing the load on your server.
## Config Options
You can use the following config options to specify the URL of an external CDN and change the cache expiration time for thumbnails and other static content:
| Environment | CLI Flag | Default | Description |
|------------------------------|---------------------|---------|-------------------------------------------------------------|
| PHOTOPRISM_CDN_URL | --cdn-url | | content delivery network `URL` |
| PHOTOPRISM_CDN_VIDEO | --cdn-video | false | stream videos over the specified CDN |
| PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` *plus* |
| PHOTOPRISM_HTTP_CACHE_PUBLIC | --http-cache-public | true | allow static content to be cached by a CDN or caching proxy |
| PHOTOPRISM_HTTP_CACHE_MAXAGE | --http-cache-maxage | 2592000 | time in `SECONDS` until cached content expires |
| PHOTOPRISM_HTTP_VIDEO_MAXAGE | --http-video-maxage | 21600 | time in `SECONDS` until cached videos expire |
> [!NOTE]
> `PHOTOPRISM_HTTP_CACHE_PUBLIC` is enabled automatically as soon as a `PHOTOPRISM_CDN_URL` is
> configured, which is why it defaults to `true` here; without a CDN it defaults to `false`, as
> shown in the [config reference](/kb/config-options/#web-server). Publicly cacheable content can be
> served by a CDN or caching proxy without accessing your instance if it is already cached.
## CDN Providers
### bunny.net
If you don't have a CDN provider yet, we can recommend [bunny.net](https://link.photoprism.app/bunny-cdn). This EU-based company has a cute name, but is a reputable provider with [excellent performance](https://www.cdnperf.com/), a wide range of features, and more than 20,000 customers including big names like Hyundai. We also chose bunny.net for our website and public demo as they are fully compliant with the GDPR.[^1]
Pricing starts at $0.005/GB and there is no minimum usage or monthly fee, so you only pay for what you actually need.
[Learn more ›](https://link.photoprism.app/bunny-cdn)
### Cloudflare
[Cloudflare](https://www.cloudflare.com/) works similar to a [reverse proxy](https://docs.photoprism.app/getting-started/proxies/traefik/), allowing you to make a private server publicly accessible over the Internet. This means that users accessing your instance through their service will only see a single URL, as if they were connecting directly.
You must therefore not configure an external CDN URL, since this could prevent PhotoPrism from loading. Also note that their free version [does not include video streaming](https://www.cloudflare.com/plans/), so there may be problems with video playback if you are not a paying customer.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
[^1]: We receive a $20 credit when you sign up through our link, which helps us fund the project infrastructure.
---
# Volume Mounts
URL: https://www.photoprism.app/plus/kb/volumes/
> Get an overview of the folders used by PhotoPrism® Plus and learn how to mount network storage.
**When using Docker, all application services run in isolated containers, so you must explicitly [mount the host folders](https://docs.docker.com/reference/compose-file/services/#volumes) you want to use. Please note that PhotoPrism and MariaDB cannot see folders that have not been mounted. This is an important security feature.**
The following paths are used on the host if you are running Linux and follow our recommendation to install PhotoPrism in `/opt/photoprism`. In the Docker container, the `/opt` prefix is omitted so that, for example, `/opt/photoprism/originals` is mounted to `/photoprism/originals`:
## Originals Folder
The *originals* folder contains your original photo and video files. By default, it is located at `/opt/photoprism/originals` on the host server and at `/photoprism/originals` in the app container. If you are using Docker Compose, you can use `~` as a shortcut for the home directory.
```yaml
volumes:
- "./originals:/photoprism/originals" # original media files (photos and videos)
```
You can mount [any folder accessible from the host](https://docs.docker.com/reference/compose-file/services/#volumes), including network shares. Additional directories can also be mounted as subfolders of `/photoprism/originals` (depending on overlay file system support):
```yaml
volumes:
- "./originals:/photoprism/originals"
- "/mnt/photos:/photoprism/originals/media"
```
On Windows, prefix the host path with the drive letter and use `/` instead of `\` as separator:
```yaml
volumes:
- "D:/Originals:/photoprism/originals"
```
> [!NOTE]
> If *read-only mode* is enabled, all features that require write permission to the *originals* folder are disabled, e.g. [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/), uploading and deleting files. Set `PHOTOPRISM_READONLY` to `"true"` in `compose.yaml` for this. You can [mount a folder with the `:ro` flag](https://docs.docker.com/reference/compose-file/services/#volumes) to make Docker block write operations as well.
## Storage Folder
SQLite, config, cache, thumbnail, and sidecar files are saved in the *storage* folder, which by default is located at `/opt/photoprism/storage` on the host server and at `/photoprism/storage` in the app container.
- a *storage* folder mount must always be configured in your `compose.yaml` or `docker-compose.yml` file so that you do not lose these files after a restart or upgrade
- never configure the *storage* folder to be inside the *originals* folder unless the name starts with a `.` to indicate that it is hidden
- we recommend placing the *storage* folder on a [local SSD drive](/plus/kb/requirements/) for best performance
- mounting [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) or using them inside the *storage* folder is currently not supported
> [!NOTE]
> Should you later want to move your instance to another host, the easiest and most time-saving way is to copy the entire *storage* folder along with your originals and database.
## Import Folder
You can optionally mount an *import* folder from which files can be transferred to the *originals* folder in a structured way that avoids duplicates:
- by default, it is located at `/opt/photoprism/import` on the host server and at `/photoprism/import` in the app container
- [imported files](https://docs.photoprism.app/user-guide/library/import/) receive a canonical filename and will be organized by year and month
- never configure the *import* folder to be inside the *originals* folder, as this will cause a loop by importing already indexed files
> [!NOTE]
> You can safely skip this. Adding files via [Web Upload](https://docs.photoprism.app/user-guide/library/upload/) and [WebDAV](https://docs.photoprism.app/user-guide/sync/webdav/) remains possible, unless [read-only mode](/plus/kb/config-options/) is enabled or the [features have been disabled](https://docs.photoprism.app/user-guide/settings/general/).
## MariaDB Database
Our example includes a pre-configured [MariaDB](https://mariadb.com/) database server that uses `/opt/photoprism/database` as storage folder. If you remove it and provide no other database server credentials, SQLite database files will be created in `/opt/photoprism/storage`.
> [!NOTE]
> Never [store database files](https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#corrupted-files) on an unreliable device such as a USB flash drive, SD card, or shared network folder. These may also have [unexpected file size limitations](https://thegeekpage.com/fix-the-file-size-exceeds-the-limit-allowed-and-cannot-be-saved/), which is especially problematic for databases that do not split data into smaller files. We strongly recommend using SSD storage for databases only, see [System Requirements](/plus/kb/requirements/)
## Network Storage
Shared folders that have already been mounted on your host can be mounted like any local drive or directory.
Alternatively, you can mount network storage with [Docker Compose](https://docs.docker.com/reference/compose-file/volumes/#driver_opts).
Please never store database files on an unreliable device such as a USB stick, SD card, or network drive.
### Unix / NFS
Follow this `compose.yaml` example to mount Network File System (NFS) shares e.g. from Unix servers or NAS devices:
```yaml
services:
photoprism:
# ...
volumes:
# Map named volume "originals"
# to "/photoprism/originals":
- "originals:/photoprism/originals"
mariadb:
# ...
# Specify named volumes:
volumes:
originals:
driver_opts:
type: nfs
# Authentication and other mounting options:
o: "addr=1.2.3.4,username=user,password=secret,soft,rw,nfsvers=4"
# Mount this path:
device: ":/mnt/example"
```
`device` should contain the path to the share on the NFS server, note the `:` at the beginning. In the above example, the share can be mounted as the named volume `originals`. You can also choose another name as long as it is consistent.
Driver-specific options can be set after the server address in `o`, see the [nfs manual page](https://man7.org/linux/man-pages/man5/nfs.5.html). Here are some examples of commonly used options:
- `nfsvers=3` or `nfsvers=4` to specify the NFS version
- `nolock` (optional): Remote applications on the NFS server are not affected by lock files inside the Docker container (only other processes inside the container are affected by locks)
- `timeo=n` (optional, default 600): The NFS client waits `n` tenths of a second before retrying an NFS request
- `soft` (optional): The NFS client aborts an NFS request after `retrans=n` unsuccessful retries, otherwise it retries indefinitely
- `retrans=n` (optional, default 2): Sets the number of retries for NFS requests, only relevant when using `soft`
### SMB / CIFS
Follow this `compose.yaml` example to mount [CIFS network shares](https://en.wikipedia.org/wiki/Server_Message_Block), e.g. **from Windows**, NAS devices or Linux servers with [Samba](https://www.samba.org/):
```yaml
services:
photoprism:
# ...
volumes:
# Map named volume "originals"
# to "/photoprism/originals":
- "originals:/photoprism/originals"
mariadb:
# ...
# Specify named volumes:
volumes:
originals:
driver_opts:
type: cifs
o: "username=user,password=secret,rw"
device: "//host/folder"
```
Then restart all services for the changes to take effect. Note that related values must start at the same indentation level [in YAML](https://docs.photoprism.app/developer-guide/technologies/yaml/) and that **tabs are not allowed for indentation**. We recommend using 2 spaces, but any number will do as long as it is consistent.
## PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
- [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/)
- [PhotoPrism® Knowledge Base](/kb/)
- [PhotoPrism® Plus Knowledge Base](/plus/kb/)
---
# Product & Pricing Pages
The following marketing pages use HTML layouts; their descriptions, prose, and feature lists are included below for ingestion.
---
# Features
URL: https://www.photoprism.app/features/
#### Feature Overview
Our mission is to provide the most user- and privacy-friendly solution to keep your pictures organized and accessible.
Simple, affordable pricing. Upgrade or downgrade at any time.
Community
€ 000 / ∞
Essentials
Plus
By using the software and services we provide, you agree to our Terms of Service, Privacy Policy, and Code of Conduct. Essentials and Plus Memberships are billed annually. When you sign up, you will be charged automatically at the beginning of each billing period until you cancel your membership. You may cancel at any time. No refund or credit for partial billing periods. If you are a consumer in the EEA, you have a statutory right of withdrawal.
1 For more information, see our detailed feature comparison chart and Membership FAQ. We recommend that new users install our free Community Edition before signing up for a membership.
2 PhotoPrism® Plus includes a web user interface for account and session management, in addition to the command-line interface available in all editions.
--- # Cloud Hosting URL: https://www.photoprism.app/cloud/Simple, affordable pricing. Upgrade or downgrade at any time.
PikaPods has partnered with us to offer you an officially supported, cloud-hosted solution. Your personal instance is ready to use in just a few steps and includes member features like premium themes and high-resolution world maps - at no additional cost! New customers also receive a $5 welcome credit.Simple, affordable pricing. Upgrade or downgrade at any time.
Starter
Business
Enterprise
A key difference between the Public License and our Pro License Agreement is that you get access to additional support and configuration options, as well as the right to customize functionality to your needs without having to publicly disclose your changes. Our Compliance FAQ gives answers to the most frequently asked questions about product scalability, support and security.
1 Billed annually. Educational institutions and non-profit organizations are welcome to contact us for a discount.
--- # Enterprise URL: https://www.photoprism.app/enterprise/ > A scalable and secure Digital Asset Management (DAM) system that helps teams organize, browse, and share photos and videos. It combines powerful AI features, search filters, metadata handling, and multi-tenant capabilities with enterprise-grade reliability and support. #### PhotoPrism® Enterprise ####A scalable and secure Digital Asset Management system for teams.
PhotoPrism® Enterprise combines powerful AI features, search filters, and metadata handling with multi-tenant capabilities, enterprise-grade reliability, and SLA-backed support, self-hosted on your own infrastructure.
Enterprise is the top tier of our Team Editions, adding an Enterprise SLA, identity management, and on-premises cluster deployment on top of the Starter and Business plans. Compare the editions to find the right fit, or get in touch for a tailored quote.
The Pro License Agreement grants access to additional support and configuration options, as well as the right to customize functionality to your needs without having to publicly disclose your changes. Our Compliance FAQ answers the most frequently asked questions about product scalability, support, and security.
--- # iOS & Android Apps URL: https://www.photoprism.app/partners/Discover compatible apps and devices that help you to get the most out of PhotoPrism®
Transfer photos & videos directly from your mobile phone! Securely backup your pictures in the background or manually select files to be uploaded to specific folders. PhotoSync works flawlessly with PhotoPrism.
