# PhotoPrism — Knowledge Base Full Text Archive > AI-powered, privacy-first, self-hosted app for browsing, organizing, and sharing photos and videos Source: https://www.photoprism.app/ Articles: 57 This file contains the full Markdown source of the PhotoPrism Knowledge Base articles, concatenated for LLM ingestion. Images are referenced by their canonical URL. For product, pricing, and company information see https://www.photoprism.app/. --- # Activating Your Membership URL: https://www.photoprism.app/kb/activation/ > This guide shows you how to create and connect your account to get full access to your member benefits. ## Step 1: Sign Up ## If you don't have a membership account with us yet, please register first at [my.photoprism.app](https://my.photoprism.app/register). Create Account chevron_right View Membership FAQ chevron_right Members who support us through **Patreon** should sign up with the same email address so that their membership can be activated automatically. This may take a few minutes. Otherwise, feel free to [contact us](/contact/) via email so we can manually activate your membership. Alternatively, if you have a **GitHub Sponsors** membership, please use the "Activate GitHub Sponsors Membership" button at the bottom of the Membership tab to submit your username and allow one day for our team to process your request. Thank you! > [!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 ## Make sure you have the latest version of PhotoPrism installed. If you don't have it installed yet, our [Setup Guide](https://docs.photoprism.app/getting-started/) will show you how to set it up and customize it to your needs in just a few steps. Follow the [Update Guide](https://docs.photoprism.app/getting-started/updates/) to learn how to download the most recent build and restart your instance. Get Started chevron_right View Releases chevron_right ## Step 3: Connect Account ## 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 ### If you have installed the [latest release](https://docs.photoprism.app/release-notes/), our [members area](https://my.photoprism.app/dashboard/membership) shows that you have successfully signed up for *Essentials*, *Plus* or a higher tier, 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: (c) Another possibility is that your instance does [not have write permissions](https://docs.photoprism.app/getting-started/troubleshooting/docker/#file-permissions) to the [`storage/config` folder](https://docs.photoprism.app/getting-started/docker-compose/#photoprismstorage), or the server time is set incorrectly, causing the maps key validation to fail. In case none of this works, or if you see an "error 403" in the debug logs when starting your instance, please don't hesitate to [contact us](mailto:membership@photoprism.app) so we can assist you. ## 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]: If you run your instance in [public mode](https://docs.photoprism.app/getting-started/config-options/#authentication), you cannot connect your [membership account](https://my.photoprism.app/), access the [user management](https://docs.photoprism.app/user-guide/users/) or change any [advanced settings](https://docs.photoprism.app/user-guide/settings/advanced/) through the user interface, as this [requires an authorized admin](https://docs.photoprism.app/user-guide/users/roles/#admin) to be logged in. [^2]: Our troubleshooting checklists help you quickly diagnose and solve common problems: --- # Application Architecture URL: https://www.photoprism.app/kb/architecture/ > Get an overview of the PhotoPrism® architecture and learn about the interaction with external services. Architecture Diagram ## 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 . ## API Documentation GoDoc automatically generates an [API reference for developers](https://pkg.go.dev/github.com/photoprism/photoprism) based on our [public source code](https://github.com/photoprism/photoprism). View REST API docs chevron_right ## Database Schema 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/) - [GitHub](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. ## 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/) --- # Compliance FAQ URL: https://www.photoprism.app/kb/compliance-faq/ > Get answers to the most frequently asked questions about product scalability, support and security. ### When was your product first developed? milestones ### 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. Compare Team Editions chevron_right ### 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. Compare Support Levels chevron_right ### 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. View Terms chevron_right View Pro License chevron_right ### 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. About PhotoPrism chevron_right Meet Our Team chevron_right ### 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. View Terms chevron_right View Pro License chevron_right ## 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/). Learn more chevron_right ### 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). View REST API docs chevron_right ## 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. View config options chevron_right ### 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. Get performance tips chevron_right ### 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: Network Diagram When in doubt, you are welcome to test the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license. Use a CDN chevron_right Get performance tips chevron_right ### 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. Get performance tips chevron_right ### 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. View Roadmap chevron_right ### 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/). Learn more chevron_right ### 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. View Release Notes chevron_right ### 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/). View Security Policy chevron_right View Known Issues chevron_right ## 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. Compare Support Levels chevron_right ### 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. View Metadata Compatibility chevron_right ### 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. View Privacy Policy chevron_right ### 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. View Privacy Policy chevron_right View GDPR Compliance Statement chevron_right *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. View GDPR Compliance Statement chevron_right ### 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. View Security Policy chevron_right ### 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 . ## API Documentation GoDoc automatically generates an [API reference for developers](https://pkg.go.dev/github.com/photoprism/photoprism) based on our [public source code](https://github.com/photoprism/photoprism). View REST API docs chevron_right ## Database Schema 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/) - [GitHub](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. ## Terms & Privacy ### Privacy Policy What information we collect, how we use it, and under what circumstances we share it is explained in our [Privacy Policy](/privacy/). Read our [GDPR Compliance Statement](/privacy/gdpr/) to learn more about the rights you have as a resident of the European Economic Area ("EEA"), our ongoing commitment to user privacy, and the General Data Protection Regulation ("GDPR"). ### Terms of Service Visit to learn how we work, what you can expect from us, and what we expect from you. ### Trademark and Brand Guidelines Our [Trademark and Brand Guidelines](/trademark/), which may be updated from time to time, describe how our brand assets may be used. It is important to us that any permitted use of our brand assets is fair and meets the highest standards. ### Community Standards By using our infrastructure, including the forums and chats we provide, you agree to our [Code of Conduct](/code-of-conduct/). It explains the "dos and don’ts" when interacting with other community members. --- # Getting Support URL: https://www.photoprism.app/kb/getting-support/ > Get information on our community support and additional support options for members. ## Community Support #### User Guide Visit [docs.photoprism.app/user-guide](https://docs.photoprism.app/user-guide/) to learn how to [sync](https://docs.photoprism.app/user-guide/sync/webdav/), [organize](https://docs.photoprism.app/user-guide/library/), and [share](https://docs.photoprism.app/user-guide/share/) your pictures. Read the docs chevron_right #### Public Forums If you need help installing our software at home, you are welcome to post your question in [GitHub Discussions](https://link.photoprism.app/discussions) or ask in our [Community Chat](https://link.photoprism.app/chat). #### Community Chat Our community chat is open to everyone, so you can connect with other users, get help, and provide help to others. Start Chatting chevron_right #### Virtual Expert Our Solution Expert on [ChatGPT](https://link.photoprism.app/chatgpt) has direct access to [our documentation](https://docs.photoprism.app/) and [knowledge bases](/kb/), ensuring accurate and reliable responses — whether it's about [configuration](https://docs.photoprism.app/getting-started/config-options/) and [troubleshooting](https://docs.photoprism.app/getting-started/troubleshooting/), [CLI commands](https://docs.photoprism.app/getting-started/docker-compose/#command-line-interface), [search filters](https://docs.photoprism.app/user-guide/search/filters/), or any other topic that's on your mind. Feel free to give it a try and let us know what you think![^1] Ask ChatGPT chevron_right #### Troubleshooting Checklists Common problems can be quickly diagnosed and solved using the [Troubleshooting Checklists](https://docs.photoprism.app/getting-started/troubleshooting/) in [Getting Started](https://docs.photoprism.app/getting-started/). Diagnose Problems chevron_right #### Known Issues Find helpful background information on currently unresolved issues and learn what workarounds are available. Learn more chevron_right ## PhotoPrism+ Membership As a member, you can additionally get access to the following support options: #### Private Chat Plus members are welcome to join our private chat on [Matrix.org](https://matrix.org/) to connect with our team and other users. #### Email Support Silver, Gold and Platinum members are also welcome to [email us for technical support and advice](/contact/). Compare Memberships chevron_right View Membership FAQ chevron_right ## Commercial Support Response and resolution times for [our team plans](/teams/) are [based on the support level](/pro/support/) you have chosen. We will make reasonable efforts to meet response and resolution times for issues that fall within the scope of our own software. Business hours are Monday through Friday from 9 am to 5 pm CET, excluding holidays. Compare Team Plans chevron_right Support & SLA Details chevron_right ## Reporting Bugs ## Before reporting a bug, please use our [Troubleshooting Checklists](https://docs.photoprism.app/getting-started/troubleshooting/) to determine the cause of your problem. If you have a general question, need help, it could be a local configuration issue, or a misunderstanding in how the software works: - you are welcome to ask in our [Community Chat](https://link.photoprism.app/chat) - or post your question in [GitHub Discussions](https://link.photoprism.app/discussions) When reporting a problem, always include the software versions you are using and [other information about your environment](/kb/reporting-bugs/) such as [browser, browser plugins](https://docs.photoprism.app/getting-started/troubleshooting/browsers/), operating system, storage type, memory size, and processor. We kindly ask you not to report bugs via GitHub Issues **unless you are certain to have found a fully reproducible and previously unreported issue** that must be fixed directly in the app. > [!NOTE] > All issue **subscribers receive an email notification** from GitHub whenever a new comment is added, so these should only be used for sharing important information and not for discussions, questions or expressing personal opinions. [^1]: ChatGPT can make mistakes and, unless you opt out, your chats may be used for training purposes. --- # Installation Packages URL: https://www.photoprism.app/kb/installation-packages/ > Learn how to set up PhotoPrism on Linux without using Docker. As an alternative to our [Docker images](https://docs.photoprism.app/getting-started/docker-compose/), you can use the packages available at [**dl.photoprism.app/pkg/linux/**](https://dl.photoprism.app/pkg/linux/) to install PhotoPrism on compatible Linux distributions without [building it from source](https://docs.photoprism.app/getting-started/faq/#building-from-source). We recommend that **only experienced users** choose this installation method, since these packages [need to be set up manually](#configuration) and [do not include the system dependencies](#dependencies) required to make use of all the features. Also note that the minimum required glibc version is 2.35, so for example Ubuntu 22.04 and Debian Bookworm will work with these binaries, but older Linux distributions may not be compatible. ## Usage ### Installation Using *tar.gz* Archives You can download and install PhotoPrism in `/opt/photoprism` by running the following commands: ``` sudo mkdir -p /opt/photoprism cd /opt/photoprism wget -c https://dl.photoprism.app/pkg/linux/amd64.tar.gz -O - | sudo tar -xz sudo ln -sf /opt/photoprism/bin/photoprism /usr/local/bin/photoprism photoprism --version ``` If your server has an **ARM-based CPU**, please make sure to install `arm64.tar.gz` instead of `amd64.tar.gz` when using the commands above. Both are linked to the [latest stable release](https://github.com/photoprism/photoprism/releases). Since the packages currently do not include a default configuration, we recommend that you create a [`defaults.yml`](https://docs.photoprism.app/getting-started/config-files/defaults/) in `/etc/photoprism` next, in which you configure the paths and other settings that you want to use for your instance. ### *.deb* Packages for Ubuntu / Debian Linux As an alternative to the plain *tar.gz* archives, that you need to unpack manually, we also offer *.deb* packages for Debian-based distributions such as Ubuntu Linux. On servers with a **64-bit Intel or AMD CPU**, our [latest stable release](https://github.com/photoprism/photoprism/releases) can be installed as follows: ``` curl -sLO https://dl.photoprism.app/pkg/linux/deb/amd64.deb sudo dpkg -i amd64.deb ``` If your server has an **ARM-based CPU**, such as a [Raspberry Pi](https://docs.photoprism.app/getting-started/raspberry-pi/), use the following commands instead: ``` curl -sLO https://dl.photoprism.app/pkg/linux/deb/arm64.deb sudo dpkg -i arm64.deb ``` This will install PhotoPrism to `/opt/photoprism` and add a `/usr/local/bin/photoprism` symlink for the CLI command. Since the packages currently do not include a default configuration, we recommend that you create a [`defaults.yml`](https://docs.photoprism.app/getting-started/config-files/defaults/) in `/etc/photoprism` next, in which you configure the paths and other settings that you want to use for your instance. ## Updates To update your installation, please stop all running PhotoPrism instances and make sure that there are [no media, database, or custom config files](#configuration) in the `/opt/photoprism` directory. You can then delete its contents with the command `sudo rm -rf /opt/photoprism/*` and install a new version as shown above. If you used a *.deb* package for the installation, you may need to remove the currently installed `photoprism` package by running `sudo dpkg -r photoprism` before you can install a new version with `sudo dpkg -i package.deb`. This is a known issue that we hope to resolve with improved packages. ## Dependencies In order to use all PhotoPrism features and have [full file format support](/kb/file-formats/), additional system dependencies **must be installed** as they are not included in the packages we provide, for example exiftool, darktable, rawtherapee, [libheif](https://dl.photoprism.app/dist/libheif/README.html), imagemagick, ffmpeg, libavcodec-extra, mariadb, sqlite3, and tzdata. The actual names may vary depending on what distribution you use. For details on the packages installed in our official Docker images, see . ## Configuration Run `photoprism --help` in a terminal to get an [overview of the command flags and environment variables](https://docs.photoprism.app/getting-started/config-options/) available for configuration. Their current values can be displayed with the `photoprism config` command. Global config defaults [can be defined in a `/etc/photoprism/defaults.yml` file](#defaultsyml). When specifying paths, `~` is supported as a placeholder for the current user's home directory, e.g. `~/Pictures`. Relative paths can also be specified via `./pathname`. If no explicit *originals*, *import* and/or *assets* path has been configured, a list of [default directory paths](https://github.com/photoprism/photoprism/blob/develop/pkg/fs/directories.go) will be searched and the first existing directory will be used for the respective path. To simplify [updates](#updates), we recommend **not to store** any media, database, or custom config files in the same directory where you installed PhotoPrism, e.g. `/opt/photoprism`, and to use a different base directory for them instead, for example `/photoprism`, `/var/lib/photoprism`, or a path relative to each user's home directory. Please keep in mind that any changes to the config options, either [through the UI](https://docs.photoprism.app/user-guide/settings/advanced/), [config files](https://docs.photoprism.app/getting-started/config-files/), or by [setting environment variables](https://docs.photoprism.app/getting-started/config-options/), require a restart to take effect. ### `defaults.yml` Global config defaults, including the config and storage paths to use, can optionally be [set with a `defaults.yml` file](https://docs.photoprism.app/getting-started/config-files/defaults/) in the `/etc/photoprism` directory (requires root privileges). A custom filename for loading the defaults can be specified with the `PHOTOPRISM_DEFAULTS_YAML` environment variable or the `--defaults-yaml` command flag. A `defaults.yml` file affects all users and should only contain values for options for which you want to set a global default, e.g.: ```yaml ConfigPath: "~/.config/photoprism" StoragePath: "~/.photoprism" OriginalsPath: "~/Pictures" ImportPath: "/media" AdminUser: "admin" AdminPassword: "insecure" AuthMode: "password" DatabaseDriver: "sqlite" JpegQuality: 85 DetectNSFW: false UploadNSFW: true ``` For a list of supported options and their names, see . When specifying values, make sure that the data type is the [same as in the documentation](https://docs.photoprism.app/getting-started/config-files/#config-options), e.g. *bool* values must be either `true` or `false` and *int* values must be whole numbers without any quotes like in the example above. ### `options.yml` Default config values can be overridden by values [specified in an `options.yml` file](https://docs.photoprism.app/getting-started/config-files/) as well as with command flags and environment variables. To load values from an existing `options.yml` file, you can specify its storage path (excluding the filename) by setting the `ConfigPath` option in your `defaults.yml` file, using the `--config-path` command flag, or with the `PHOTOPRISM_CONFIG_PATH` environment variable. The values in an `options.yml` file are not global and can be used to customize individual instances e.g. based on the default values in a `defaults.yml` file. Both files allow you to set any of the [supported options](https://docs.photoprism.app/getting-started/config-files/#config-options). ## Documentation For detailed information on specific features and related resources, see our [Knowledge Base](https://www.photoprism.app/kb/), or check the [User Guide](https://docs.photoprism.app/user-guide/) for help [navigating the user interface](https://docs.photoprism.app/user-guide/navigate/), a [complete list of config options](https://docs.photoprism.app/getting-started/config-options/), and [other installation methods](https://docs.photoprism.app/getting-started/): - [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/) - [PhotoPrism® Developer Guide](https://docs.photoprism.app/developer-guide/) - [PhotoPrism® Knowledge Base](https://www.photoprism.app/kb/) ## Getting Support If you need help installing our software at home, you are welcome to post your question in [GitHub Discussions](https://link.photoprism.app/discussions) or ask in our [Community Chat](https://link.photoprism.app/chat). Common problems can be quickly diagnosed and solved using our [Troubleshooting Checklists](https://docs.photoprism.app/getting-started/troubleshooting/). [Silver, Gold, and Platinum](https://link.photoprism.app/membership) members are also welcome to email us for technical support and advice. [View Support Options ›](https://www.photoprism.app/kb/getting-support/) --- # Metadata Compatibility URL: https://www.photoprism.app/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 | exif:GPSAltitude | | | Aperture | decimal | ApertureValue, Aperture | exif:ApertureValue | | | FNumber | decimal | FNumber | exif:FNumber | | | FPS | decimal | VideoFrameRate, VideoAvgFrameRate | | | | FocalDistance | decimal | HyperfocalDistance | | | | Duration | duration | Duration, MediaDuration, TrackDuration, PreviewDuration | | | | Favorite | flag | Favorite | fstop:favorite | | | Flash | flag | FlashFired | exif:Flash/exif:Fired | | | Keywords | list | Keywords | | | | FocalLength | number | FocalLength, FocalLengthIn35mmFormat | exif:FocalLength, exif:FocalLengthIn35mmFilm | | | Frames | number | FrameCount, AnimationFrames | | | | Height | number | ImageHeight, ImageLength, PixelYDimension, ExifImageHeight, SourceImageHeight | | | | ImageType | number | HDRImageType | | | | Iso | number | ISO | exifEX:PhotographicSensitivity, exif:ISOSpeedRatings | | | Pages | number | PageCount, NPages, Pages | | | | Rotation | number | Rotation | | | | Width | number | ImageWidth, PixelXDimension, ExifImageWidth, SourceImageWidth | | | | Artist | text | Artist, Creator, By-line, OwnerName, Owner | dc:creator | creator | | CameraMake | text | CameraMake, Make | tiff:Make | | | CameraModel | text | CameraModel, Model, CameraID, UniqueCameraModel | tiff:Model | | | CameraOwner | text | OwnerName | aux:OwnerName | | | CameraSerial | text | SerialNumber | exifEX:BodySerialNumber, aux:SerialNumber | | | Caption | text | Description, ImageDescription, Caption, Caption-Abstract | dc:description, tiff:ImageDescription | description, description.Alt | | Codec | text | CompressorID, VideoCodecID, CodecID, OtherFormat, VideoCodec, FileType | | | | ColorProfile | text | ICCProfileName, ProfileDescription | photoshop:ICCProfile | | | Copyright | text | Rights, Copyright, CopyrightNotice, WebStatement | dc:rights, tiff:Copyright, xmpRights:WebStatement | rights, rights.Alt | | DocumentID | text | ContentIdentifier, MediaGroupUUID, BurstUUID, OriginalDocumentID, DocumentID, ImageUniqueID, DigitalImageGUID | xmpMM:OriginalDocumentID, xmpMM:DocumentID, dc:identifier | identifier | | Exposure | text | ExposureTime, ShutterSpeedValue, ShutterSpeed, TargetExposureTime | exif:ExposureTime, exif:ShutterSpeedValue | | | FileName | text | FileName | | | | GPSLatitude | text | GPSLatitude | exif:GPSLatitude | | | GPSLongitude | text | GPSLongitude | exif:GPSLongitude | | | GPSPosition | text | GPSPosition | | | | InstanceID | text | InstanceID, DocumentID | xmpMM:InstanceID | | | LensMake | text | LensMake | exifEX:LensMake | | | LensModel | text | LensModel, Lens, LensID | exifEX:LensModel, aux:Lens, aux:LensID | | | License | text | UsageTerms, License | xmpRights:UsageTerms | | | Notes | text | Comment, UserComment | exif:UserComment | | | Projection | text | ProjectionType | GPano:ProjectionType | | | Software | text | Software, Producer, CreatorTool, CreatorSubTool, HistorySoftwareAgent, ProcessingSoftware | xmp:CreatorTool, tiff:Software | | | Subject | text | Subject, PersonInImage, ObjectName, HierarchicalSubject, CatalogSets | dc:subject, Iptc4xmpExt:PersonInImage, lr:hierarchicalSubject | subject | | TimeOffset | text | OffsetTime, OffsetTimeOriginal, OffsetTimeDigitized | exif:OffsetTimeOriginal, exif:OffsetTime, exif:OffsetTimeDigitized | | | Title | text | Title, Headline | dc:title, photoshop:Headline | title, title.Alt | | CreatedAt | timestamp | SubSecCreateDate, CreationTime, CreationDate, CreateDate, MediaCreateDate, ContentCreateDate, TrackCreateDate | xmp:CreateDate, xmpDM:CreationDate | | | TakenAt | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationTime, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | photoshop:DateCreated, exif:DateTimeOriginal, xmp:CreateDate | | | TakenAtLocal | timestamp | SubSecDateTimeOriginal, SubSecDateTimeCreated, DateTimeOriginal, CreationDate, DateTimeCreated, DateTime, DateTimeDigitized | photoshop:DateCreated, exif:DateTimeOriginal, xmp:CreateDate | | | TakenGps | timestamp | GPSDateTime, GPSDateStamp | exif:GPSTimeStamp, exif:GPSDateStamp | | ## Metadata Tags by Namespace ## | Namespace | Documentation | |:--------------------|:---------------------------------------------------------------------| | Exiftool | https://exiftool.org/TagNames/EXIF.html | | Exiftool XMP | https://exiftool.org/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. --- # Personal Memberships URL: https://www.photoprism.app/kb/personal/
Community Essentials Plus PikaPods
Price FREE € 2.00 / mo from € 6.00 / mo from $ 6.50 / mo
Installation Self-Hosted Self-Hosted Self-Hosted Fully Managed
Help & Support Public Forums &
Community Chat
Public Forums &
Community Chat
Private Chat Provider
Storage Limit unlimited unlimited unlimited flexible
Instances unlimited personal use personal use flexible
Back Our Mission
Full Data Ownership
Regular Updates
AGPL License
Plus License
Docker Images
Linux Packages
Build from Source
Invoice with VAT-ID
Mobile Apps PWA & PhotoSync PWA & PhotoSync PWA & PhotoSync PWA & PhotoSync
Accessible over the Internet optional optional optional
Access Control
Account Roles Super Admin, Admin, Guest Super Admin, Admin, User, Viewer, Guest Super Admin, Admin, User, Viewer, Guest Super Admin, Admin, User, Viewer, Guest
Admin Web UI
CLI Commands
Login with 2FA
App Passwords
Client Credentials
Session Monitoring
Hardened Security
Custom Rate Limits
Single Sign-On (SSO) OpenID Connect OpenID Connect OpenID Connect
Artificial Intelligence
People & Faces
Caption Generation Ollama, OpenAI Ollama, OpenAI Ollama, OpenAI Ollama Cloud
Label Generation
Custom Labels Ollama, OpenAI, TensorFlow Ollama, OpenAI, TensorFlow Ollama, OpenAI, TensorFlow Ollama Cloud
NSFW Detection
Media Library
Keep Folder Structure
Duplicate Detection
Scheduled Indexing
Automatic Stacking
Automatic Organization optional optional optional optional
Supported File Formats
Maximum Resolution 900 MP 900 MP 900 MP 150 MP
JPEG, PNG & HEIC
JPEG XL
RAW Images
Videos
Live Photos
Motion Photos
360° Panoramas 16K 16K 16K 16K
Animated GIFs
Adobe PDF
Vector Graphics
Metadata Compatibility
ICC Color Profiles
Exif Metadata
Google Photos
ExifTool JSON
YAML Sidecar Files
Adobe XMP
Search
Powerful Filters
Fast Scrolling
Sort Results
Browse
People
Places
Moments
Calendar
Labels
Folders
Document Viewer
Maps & Places
Interactive World Maps High-Resolution
Vector Map
3D Vector &
Satellite Maps
3D Vector &
Satellite Maps
3D Vector &
Satellite Maps
Reverse Geocoding Rate Limited No Request Limit &
Redundant API
No Request Limit &
Redundant API
No Request Limit &
Redundant API
Location Estimates
Location Updates
Organization
Albums
Favorites
Edit Metadata
Quality Review
Archive & Delete
Hide Private
Hide People
Batch Edit
Sharing
WebDAV Upload
Download as ZIP
Album Links
File Links hourglass_top hourglass_top hourglass_top hourglass_top
Remote Access
WebDAV Server
Web Upload & Download
HTTPS optional optional optional
Domain Name optional optional optional
VPN optional optional optional
Backup
Database Backups manual, scheduled manual, scheduled manual, scheduled scheduled
Remote File Sync
YAML Sidecar Files
User Interface
Multiple Languages
Premium Themes
Configuration
Advanced Settings
Plus Security
Mobile App (PWA)
Login Wallpaper
Legal Information
Social Preview
Video Transcoding
Content Delivery Network (CDN) optional optional optional optional
Community Essentials Plus PikaPods
Get Started Sign Up Sign Up Sign Up
--- # Reporting Bugs URL: https://www.photoprism.app/kb/reporting-bugs/ > When reporting a problem, always include the software versions you use and other information about your environment, such as browser, operating system, memory, storage, and processor. **We kindly ask you not to report bugs via *GitHub Issues* unless you are certain to have found a fully reproducible and previously unreported issue that must be fixed directly in the app.** Ask for [technical support](/kb/getting-support/) if you need help, it could be a local configuration problem, or a misunderstanding in how the software works. #### 1. What is not working as documented? Be as specific as possible and explain which part of the software is not [working as documented](https://docs.photoprism.app/), e.g. "image not found" or "wrong thumbnail" would not be detailed enough. Links to the related documentation on [docs.photoprism.app](https://docs.photoprism.app/): - ... *Please never report [known issues](https://docs.photoprism.app/known-issues/) or [missing features](https://github.com/photoprism/photoprism/issues) as bugs, and do not submit bug reports for the purpose of getting [technical support](https://www.photoprism.app/kb/getting-support/) or because you have not received a response in our [public community forums](https://github.com/photoprism/photoprism/discussions). Thank you very much!* #### 2. How can we reproduce it? Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error When reporting an import, indexing, or performance issue, please include the number and type of pictures in your library, as well as any configuration options you have changed, such as for thumbnail quality. #### 3. What behavior do you expect? Give us a clear and concise description of what you expect. #### 4. What could be the cause of your problem? Always try to determine the cause of your problem using the checklists at before submitting a bug report. #### 5. Can you provide us with example files for testing, error logs, or screenshots? Please include sample files or screenshots that help to reproduce your problem. You can also email files or share a download link, see for details. Visit to learn how to diagnose frontend issues. > [!NOTE] > **If it is an import, indexing or metadata issue, we require sample files and logs from you.** Otherwise, we will not be able to process your report. If it is an import problem specifically, please always provide us with an archive of the files before you imported them so we can reproduce the behavior. #### 6. Which software versions do you use? (a) PhotoPrism Architecture & Build Number: AMD64, ARM64, ARMv7,... (b) Database Type & Version: MariaDB, MySQL, SQLite,... (c) Operating System Types & Versions: Linux, Windows, Android,... (d) Browser Types & Versions: Firefox, Chrome, Safari on iPhone,... (e) Ad Blockers, Browser Plugins, and/or Firewall Software? You can find the version/build number of the app in *Settings* by scrolling to the bottom. Note that MySQL 8 support has been discontinued, see system requirements at . *Always provide database and operating system details if it is a backend, import, or indexing issue. Should it be a frontend issue, at a minimum we require you to provide web browser and operating system details. When reporting a performance problem, we ask that you provide us with complete information about your environment, as there may be more than one cause.* #### 7. On what kind of device is PhotoPrism installed? This is especially important if you are reporting a performance, import, or indexing issue. You can skip this if you're reporting a problem you found in our public demo, or if it's a completely unrelated issue, such as incorrect page layout. (a) Device / Processor Type: Raspberry Pi 4, Intel Core i7-3770, AMD Ryzen 7 3800X,... (b) Physical Memory & Swap Space in GB (c) Storage Type: HDD, SSD, RAID, USB, Network Storage,... (d) Anything else that might be helpful to know? *Always provide device, memory, and storage details if you have a backend, performance, import, or indexing issue.* #### 8. Do you use a Reverse Proxy, Firewall, VPN, or CDN? If yes, please specify type and version. You can skip this if you are reporting a completely unrelated issue. *Always provide this information when you have a reliability, performance, or frontend problem, such as failed uploads, connection errors, broken thumbnails, or video playback issues.* **Using NGINX?** Please also provide the configuration and/or consider asking the NGINX community for advice as we do not specialize in supporting their product. Docs can be found at . --- # Search Filter Reference URL: https://www.photoprism.app/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/) --- # Supported File Formats URL: https://www.photoprism.app/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, .mp.jpeg, .mp.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 | --- # Team Editions URL: https://www.photoprism.app/kb/teams/
Starter Business Enterprise
Team License € 79.00 / mo1 from € 219.00 / mo1 from € 1499.00 / mo1
Customer Support Email & Chat during Business Hours Support Level Agreement (SLA) Enterprise SLA
First Response Best Effort 24 Business Hours 8 Business Hours
Storage Limit unlimited unlimited unlimited
Runs On-Premises
Full Data Ownership
GDPR Compliant
DPA / AVV standard standard custom
Regular Updates
Docker Images
Helm Chart
Source Available
Business Invoice
Mobile Apps PWA & PhotoSync PWA & PhotoSync PWA & PhotoSync
Accessible over the Internet optional optional optional
Professional Services
Remote Setup € 499.00
Onboarding € 179.00 / hour
Branded Theme € 499.00 € 499.00
Migration Support € 179.00 / hour € 179.00 / hour
Other Services € 179.00 / hour € 179.00 / hour € 179.00 / hour
Access Control
Account Roles Super Admin, Admin, Manager, User, Viewer, Contributor, Guest Super Admin, Admin, Manager, User, Viewer, Contributor, Guest Super Admin, Admin, Manager, User, Viewer, Contributor, Guest
User Accounts up to 10 25 - 150 custom
Guest Accounts up to 50 unlimited unlimited
Admin Web UI
CLI Commands
Login with 2FA
App Passwords
Client Credentials
Session Monitoring
Intrusion Prevention
Custom Rate Limits
Security Audit Logs
Identity Management LDAP, Active Directory LDAP, Active Directory LDAP, Active Directory
Security Groups LDAP, OIDC LDAP, OIDC LDAP, OIDC
Single Sign-On (SSO) OpenID Connect OpenID Connect OpenID Connect
Artificial Intelligence
People & Faces
Caption Generation Ollama, OpenAI Ollama, OpenAI Ollama, OpenAI
Label Generation
Custom Labels Ollama, OpenAI, TensorFlow Ollama, OpenAI, TensorFlow Ollama, OpenAI, TensorFlow
NSFW Detector
Media Library
Keep Folder Structure
Duplicate Detection
Scheduled Indexing
Automatic Stacking
Automatic Organization optional optional optional
Supported File Formats
Maximum Resolution 900 MP 900 MP 900 MP
JPEG, PNG & HEIC
JPEG XL
RAW Images
Videos
Live Photos
Motion Photos
360° Panoramas 16K 16K 16K
Animated GIFs
Adobe PDF
Vector Graphics
Metadata Compatibility
ICC Color Profiles
Exif Metadata
Google Photos
ExifTool JSON
YAML Sidecar Files
Adobe XMP
Search
Powerful Filters
Fast Scrolling
Sort Results
Browse
People
Places
Moments
Calendar
Labels
Folders
Document Viewer
Maps & Places
Interactive World Maps 3D Vector & Satellite 3D Vector & Satellite 3D Vector & Satellite
Reverse Geocoding No Request Limit &
Redundant API
No Request Limit &
Redundant API
No Request Limit &
Redundant API
Location Estimates
Location Updates
Organization
Albums
Favorites
Edit Metadata
Quality Review
Archive & Delete
Hide Private
Hide People
Batch Edit
Sharing
Shared Folders
WebDAV Upload
Download as ZIP
Album Links
File Links hourglass_top hourglass_top hourglass_top
Remote Access
Web Upload & Download
WebDAV Server
REST API
HTTPS
Backup
Database Backups manual, scheduled manual, scheduled manual, scheduled
Remote File Sync
YAML Sidecar Files
User Interface
Multiple Languages
Pro Themes
Extend JS & CSS
Configuration
Advanced Settings
Pro Security
Mobile App (PWA)
Login Wallpaper
Legal Information
Social Preview
Video Transcoding
Content Delivery Network (CDN) optional optional optional
Starter Business Enterprise
Contact Us Contact Us Contact Us
--- # Using a Content Delivery Network URL: https://www.photoprism.app/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. Network Diagram ## 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 Bunny CDN 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 [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 [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. Contact Us chevron_right > [!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. Get Started chevron_right View Releases chevron_right > [!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: (c) Another possibility is that your instance does [not have write permissions](https://docs.photoprism.app/getting-started/troubleshooting/docker/#file-permissions) to the [`storage/config` folder](https://docs.photoprism.app/getting-started/docker-compose/#photoprismstorage), or the server time is set incorrectly, causing the key validation to fail. In case none of this works, or if you see an "error 403" in the debug logs when starting your instance, please don't hesitate to [contact us](mailto:support@photoprism.app) so we can assist you. Get Support chevron_right ## 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]: If you run your instance in [public mode](https://docs.photoprism.app/getting-started/config-options/#authentication), you cannot connect your [customer account](https://my.photoprism.app/), access the [user management](https://docs.photoprism.app/user-guide/users/) or change any [advanced settings](https://docs.photoprism.app/user-guide/settings/advanced/) through the user interface, as this [requires an authorized admin](https://docs.photoprism.app/user-guide/users/roles/#admin) to be logged in. [^2]: Our troubleshooting checklists help you quickly diagnose and solve common problems: --- # Application Architecture URL: https://www.photoprism.app/pro/kb/architecture/ > Get an overview of the PhotoPrism® Pro architecture and learn about the interaction with external services. Architecture Diagram ## 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 . ## API Documentation GoDoc automatically generates an [API reference for developers](https://pkg.go.dev/github.com/photoprism/photoprism) based on our [public source code](https://github.com/photoprism/photoprism). View REST API docs chevron_right ## Database Schema 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/) - [GitHub](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. ## 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/) --- # Backup Guide URL: https://www.photoprism.app/pro/kb/backups/ > Easily back up and restore your PhotoPrism® Pro media library, sidecar files, index, and configuration. **At a minimum, a backup of PhotoPrism Pro should include the files in your [*originals* folder](/pro/kb/volumes/) and a [copy of the index database](https://mariadb.com/kb/en/mariadb-dump/). We also recommend backing up the [*storage* folder](/pro/kb/volumes/) so that you don't need to recreate any thumbnail or sidecar files, and your backup includes all [config files](/pro/kb/config-options/), [certificates](/pro/kb/https/), and [customizations](/pro/kb/customization/).** #### MariaDB The easiest way to create a full backup is to first run the backup command to generate a MariaDB database dump as shown below. Then back up your *originals* and *storage* folders using any standard file backup utility. #### SQLite If you use SQLite, a full backup of both folders is mandatory, but it is not necessary to create a dump first, as there already is a copy of the index database in the storage folder. ## Important Folders #### Originals 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. You can back it up and restore it using any standard file backup utility if you haven't already set this up. #### Storage 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. We recommend that you back up this folder as well so that you don't need to recreate the thumbnails and have a complete backup of your configuration. As for the *originals* folder, you can use any standard file backup utility to do this. ## Backup Command The easiest way to create an index SQL backup dump is to run this command in a terminal: ``` docker compose exec photoprism photoprism backup -i -f ``` If you are using Podman on a Red Hat-compatible Linux distribution: ``` podman-compose exec photoprism photoprism backup -i -f ``` By default, a backup is created in `storage/backup/mysql/[YYYY-MM-DD].sql`. A custom backup folder can be configured with [`PHOTOPRISM_BACKUP_PATH`](/pro/kb/config-options/). Omit the `-f` flag if you do not want to overwrite existing files. You can also specify a custom filename as an argument (or `-` to write the SQL dump to stdout): ``` docker compose exec photoprism photoprism backup -i [filename] ``` The easiest way to create a full backup is to run the backup command before backing up your *storage* folder. How to create SQL dumps from SQLite is shown in our [advanced backup guide](https://docs.photoprism.app/getting-started/advanced/backups/). > [!NOTE] > Note that 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. > [!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). ## Restore Command To restore the index from an existing database dump, you can run the following command: ``` docker compose exec photoprism photoprism restore -i -f ``` If you are using Podman on a Red Hat-compatible Linux distribution: ``` podman-compose exec photoprism photoprism restore -i -f ``` This will automatically search the backup folder for the most recent index dump and restore it. A custom backup folder can be configured with [`PHOTOPRISM_BACKUP_PATH`](/pro/kb/config-options/). Omit the -f flag to prevent overwriting an existing index. As with the backup command, you can also specify a specific dump filename as an argument: ``` docker compose exec photoprism photoprism restore -i [filename] ``` When the database is restored, all user accounts and passwords are restored as well. If users have changed their password, they will have to log in with their old password. > [!NOTE] > If you have a backup copy of your *storage* and *originals* folders, the easiest way is to restore those folders first and then run the restore command in case you are using MariaDB. Otherwise, you additionally need to perform a complete rescan of your library to recreate missing sidecar and thumbnail files. Some of the metadata and your albums can also be recovered from YAML sidecar files even if you don't have a copy of the index database, unless you have disabled this feature. ## 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/) --- # Cluster Command-Line Tools URL: https://www.photoprism.app/pro/kb/cluster-cli/ > Register nodes, manage instances, and grant access from the command line with the photoprism cluster commands. The `photoprism cluster` commands manage a [PhotoPrism® Portal](/pro/kb/portal/) cluster from a terminal. Some commands run on an **instance** (to join a cluster and pull its theme), while the cluster-management commands run on the **Portal**, where they operate directly on the cluster registry. > [!NOTE] > Run these commands [in a terminal](https://docs.photoprism.app/getting-started/docker-compose/#opening-a-terminal), for example `docker compose exec photoprism photoprism cluster summary`. Users of Red Hat Enterprise Linux® and compatible distributions can substitute `docker` and `docker compose` with `podman` and `podman-compose`. ## Commands on a Node These commands are available on every instance and are used to join a cluster and keep its theme up to date. ### Registering a Node `photoprism cluster register` registers the current node with the Portal, or updates its credentials. It is normally run automatically on startup (see [Adding Instances](/pro/kb/portal/#adding-instances)), but you can run it manually to preview the request or to persist the returned credentials: ```bash photoprism cluster register --name acme --role instance --write-config ``` | Command Flag | Description | |-----------------------|----------------------------------------------------------------------------| | `--name NAME` | node name (lowercase letters, digits, hyphens) | | `--role ROLE` | node role, `instance` (default) or `service` | | `--portal-url URL` | Portal base URL (defaults to the configured value) | | `--join-token TOKEN` | Portal join token (defaults to the configured value) | | `--advertise-url URL` | internal URL the Portal uses to reach this node | | `--site-url URL` | public site URL (`https://...`) | | `--label k=v` | attach a label; repeat to add more | | `--rotate` | rotate the node's database password | | `--rotate-secret` | rotate the node's client secret | | `--write-config` | persist returned secrets and database settings to the local config | | `--force, -f` | confirm actions that may overwrite local data (e.g. with `--write-config`) | | `--dry-run, --dry` | print the derived values and request payload without contacting the Portal | > [!NOTE] > Secrets are printed only once, when they are first issued or rotated, and are written to disk only with `--write-config` (with strict `0600` permissions). They are never written to log files. ### Generating a Join Token `photoprism cluster join-token` generates a Portal join token that instances use to register. Use `--save` to write it to the Portal's secrets directory: ```bash photoprism cluster join-token --save ``` ### Pulling the Theme `photoprism cluster theme pull` downloads the [branding theme](/pro/kb/portal/#theme) from the Portal and installs it locally. If only a join token is available, the command registers the node first to obtain credentials, then downloads the theme: ```bash photoprism cluster theme pull ``` | Command Flag | Description | |--------------------------|--------------------------------------------------------------------------| | `--dest PATH` | extract to a different directory (defaults to the configured theme path) | | `--force, -f` | replace existing files at the destination | | `--portal-url URL` | Portal base URL (defaults to the configured value) | | `--join-token TOKEN` | Portal join token (defaults to the configured value) | | `--client-id ID` | node client ID (defaults to the configured value) | | `--client-secret SECRET` | node client secret (defaults to the configured value) | ## Commands on the Portal These commands run on the Portal and operate on the cluster registry. They accept a target node by its `UUID` (preferred), its client ID, or its name. ### Cluster Status ```bash photoprism cluster summary # cluster UUID, network, node count, database, and theme version photoprism cluster health # current cluster health status ``` ### Managing Nodes ```bash photoprism cluster nodes ls # list registered nodes photoprism cluster nodes show acme # show details for one node photoprism cluster nodes mod acme --role service --advertise-url http://acme:2342 photoprism cluster nodes rotate acme --db # rotate the database password (use --secret for the client secret) photoprism cluster nodes rm acme # remove a node (add --drop-db to also drop its database) ``` | Command | Description | |----------------|----------------------------------------------------------------------------------| | `nodes ls` | list registered nodes (`--count`, `--offset` for paging) | | `nodes show` | show a node's details, including its database driver | | `nodes mod` | change a node's role, display name, advertise URL, or labels | | `nodes rotate` | rotate a node's database password (`--db`) and/or client secret (`--secret`) | | `nodes rm` | remove a node from the registry; `--drop-db` also drops its provisioned database | > [!NOTE] > Destructive commands (`nodes mod`, `nodes rm`, `nodes rotate`) prompt for confirmation. Pass `--yes` (`-y`) to run them non-interactively, or `--dry-run` to preview the effect without making changes. ### Granting User Access The `cluster users access` commands manage which users can open which instances (see [Cluster Authentication & Access Control](/pro/kb/openid-connect/#cluster-authentication)): ```bash photoprism cluster users access ls --user [user-uid] photoprism cluster users access grant --user [user-uid] --node [node-uuid] --role viewer photoprism cluster users access revoke --user [user-uid] --node [node-uuid] ``` To admit a whole [security group](/pro/kb/openid-connect/#security-groups) to an instance, use `cluster nodes allow-group`: ```bash photoprism cluster nodes allow-group [node-uuid] [group-id] --role user ``` ## Output Formats Most cluster commands support machine-readable output for scripting and automation: | Command Flag | Description | |--------------|--------------------------------------| | `--json, -j` | print a single JSON document | | `--md, -m` | format as Markdown | | `--csv, -c` | export as semicolon separated values | | `--tsv, -t` | export as tab separated values | When `--json` is set, the command prints only the JSON result and suppresses interactive messages, so it can be piped into tools such as `jq`. ## Exit Codes The cluster commands return predictable exit codes for use in scripts: | Code | Meaning | |------|------------------------------------------------------------------| | `0` | success | | `1` | unexpected or internal error | | `2` | usage or validation error (e.g. invalid flag or name) | | `3` | not found (e.g. unknown node ID or name) | | `4` | unauthorized (missing or invalid token, insufficient privileges) | | `5` | conflict (e.g. name already in use, rotation rejected) | | `6` | rate-limited (the Portal returned too many requests) | ## 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/) --- # Command-Line Interface URL: https://www.photoprism.app/pro/kb/cli/ > Learn how to open a terminal session and use the command-line interface to perform administrative tasks. ## Introduction `photoprism help` lists all commands and [config options](/pro/kb/config-options/) available in the current version: ```bash docker compose exec photoprism photoprism help ``` Use the `--help` flag to see a detailed command description, for example: ```bash docker compose exec photoprism photoprism backup --help ``` PhotoPrism's command-line interface is also well suited for job automation e.g. using a scheduler. > [!NOTE] > When using *Docker Compose*, you can prefix the commands you want to run with `docker compose exec [service]` to execute them in the specified service container. If this fails with *no container found*, please make sure that the service has been started, you have specified an existing service (usually `photoprism`) and you are in the folder where your `compose.yaml` or `docker-compose.yml` file is located. ## Opening a Terminal To open a terminal session as the [default user](https://docs.docker.com/reference/compose-file/services/#user): ```bash docker compose exec photoprism bash ``` Since the above will open the terminal as root by default, we recommend that you pass the `-u` flag to explicitly open a non-root session if PhotoPrism is running under a specific user account, for example: ```bash docker compose exec -u 1000 photoprism bash ``` This avoids potential [filesystem permission issues](https://docs.photoprism.app/getting-started/troubleshooting/docker/#file-permissions) that can occur when a command creates new files or folders, e.g. to store thumbnails. ## Changing the User ID Specifying a user with the `-u` flag is possible for all commands you run with [Docker](https://docs.photoprism.app/getting-started/docker/#command-line-interface) and Docker Compose. In the following examples, it is omitted for brevity. Note, however, that commands that you run without an explicit user ID might be executed as root. The currently supported user ID ranges are 0, 33, 50-99, 500-600, 900-1250, and 2000-2100. > [!NOTE] > We recommend running the `photoprism` service as a non-root user by setting either the [user service property](https://docs.docker.com/reference/compose-file/services/#user) or the `PHOTOPRISM_UID` [environment variable](/pro/kb/config-options/) in your `compose.yaml` or `docker-compose.yml` file. Don't forget to update file permissions and/or ownership with the `chown` command when you make changes. ## Examples | Action | Command | |------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | *Start Services* | `docker compose up -d` | | *Stop Services* | `docker compose stop` | | *Download Updates* | `docker compose pull` | | *Uninstall* | `docker compose rm -s -v` | | [*Watch Logs*](https://docs.photoprism.app/getting-started/troubleshooting/logs/#__tabbed_1_3) | `docker compose logs -f --tail=100` | | *Display Config Values* | `docker compose exec photoprism photoprism show config` | | *Show Migration Status* | `docker compose exec photoprism photoprism migrations ls` | | *Repeat Failed Migrations* | `docker compose exec photoprism photoprism migrations run -f` | | *Reset Database* | `docker compose exec photoprism photoprism reset --yes` | | *Backup Database* | `docker compose exec photoprism photoprism backup -a -i` | | *Restore Database* | `docker compose exec photoprism photoprism restore -a -i` | | *Change Password* | `docker compose exec photoprism photoprism passwd [username]` | | *Remove Password* | `docker compose exec photoprism photoprism passwd --rm [username]` | | *Show User Management Commands* | `docker compose exec photoprism photoprism users help` | | *Reset User Accounts* | `docker compose exec photoprism photoprism users reset --yes` | | *Reset Sessions and Access Tokens* | `docker compose exec photoprism photoprism auth reset --yes` | | *Show Face Recognition Commands* | `docker compose exec photoprism photoprism faces help` | | *Index Faces* | `docker compose exec photoprism photoprism faces index` | | *Reset People & Faces* | `docker compose exec photoprism photoprism faces reset -f` | | *Transcode Videos to AVC* | `docker compose exec photoprism photoprism convert` | | *Regenerate Thumbnails* | `docker compose exec photoprism photoprism thumbs -f` | | [*Update Index*](https://docs.photoprism.app/user-guide/library/originals/) | `docker compose exec photoprism photoprism index --cleanup` | | [*Move to Originals*](https://docs.photoprism.app/user-guide/library/import/) | `docker compose exec photoprism photoprism import [path]` | | [*Copy to Originals*](https://docs.photoprism.app/user-guide/library/import/) | `docker compose exec photoprism photoprism cp [path]` | *Note that 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.* > [!NOTE] > `docker compose exec photoprism photoprism index -f` rescans all originals, including already indexed and unchanged files. This may be necessary after major upgrades and after migrations of the database schema, especially if search results are missing or incorrect. Note you can also start a [rescan from the user interface](https://docs.photoprism.app/user-guide/library/originals/) by navigating to *Library* > *Index*, checking "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". ## 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/) --- # Config Options URL: https://www.photoprism.app/pro/kb/config-options/ > Get an overview of the global config variables and command-line flags available in PhotoPrism® Pro. ### 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_ADMIN_SCOPE | --admin-scope | * | admin authorization `SCOPE` as space-separated resources, or '*' for full access *pro* | | PHOTOPRISM_PASSWORD_LENGTH | --password-length | 8 | minimum password `LENGTH` in characters | | 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_URI | --login-uri | | custom login page `URI` *pro* | | PHOTOPRISM_LOGIN_INFO | --login-info | | custom login footer info `TEXT` *pro* | | 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 | | PHOTOPRISM_LDAP_URI | --ldap-uri | | LDAP directory `URI`, e.g. ldaps://example.com:636 for LDAP over SSL/TLS *pro* | | PHOTOPRISM_LDAP_CERT | --ldap-cert | | LDAP directory SSL/TLS certificate `FILENAME` (.pem) *pro* | | PHOTOPRISM_LDAP_INSECURE | --ldap-insecure | false | skips SSL/TLS certificate verification when using LDAPS *pro* | | PHOTOPRISM_LDAP_CHASE | --ldap-chase | false | automatically chases referrals when there are multiple LDAP servers *pro* | | PHOTOPRISM_LDAP_CHASE_INSECURE | --ldap-chase-insecure | false | skips SSL/TLS certificate verification when chasing referrals *pro* | | PHOTOPRISM_LDAP_SYNC | --ldap-sync | false | updates name, email, role, and attributes from LDAP directory on login *pro* | | PHOTOPRISM_LDAP_BIND | --ldap-bind | simple | LDAP authentication `TYPE` (simple, md5) *pro* | | PHOTOPRISM_LDAP_BIND_DN | --ldap-bind-dn | userprincipalname | LDAP username attribute `DN`, e.g. cn or userprincipalname *pro* | | PHOTOPRISM_LDAP_BASE_DN | --ldap-base-dn | | LDAP directory base `DN`, e.g. dc=example,dc=com *pro* | | PHOTOPRISM_LDAP_ROLE | --ldap-role | | LDAP default `ROLE` (admin, manager, user, contributor, viewer, or guest), leave blank for none *pro* | | PHOTOPRISM_LDAP_ROLE_DN | --ldap-role-dn | | custom LDAP group or attribute `DN` for specifying the role *pro* | | PHOTOPRISM_LDAP_NOLOGIN | --ldap-nologin | false | disables web login for new LDAP users by default *pro* | | PHOTOPRISM_LDAP_NOLOGIN_DN | --ldap-nologin-dn | | custom LDAP attribute `DN` to disable web login *pro* | | PHOTOPRISM_LDAP_WEBDAV | --ldap-webdav | false | allows new LDAP users to use WebDAV when they have a role that allows it *pro* | | PHOTOPRISM_LDAP_WEBDAV_DN | --ldap-webdav-dn | | custom LDAP attribute `DN` to enable WebDAV access *pro* | | PHOTOPRISM_LDAP_BASE_PATH_DN | --ldap-base-path-dn | | user base path LDAP attribute `DN` *pro* | | PHOTOPRISM_LDAP_UPLOAD_PATH_DN | --ldap-upload-path-dn | | user upload path LDAP attribute `DN` *pro* | | PHOTOPRISM_DISABLE_LDAP | --disable-ldap | false | disables authentication via LDAP *pro* | | 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_AUDIT_LEVEL | --audit-level | warning | audit log recording `LEVEL` (debug, info, warning, error) *pro* | | 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_CUSTOM_ASSETS_PATH | --custom-assets-path | | assets `PATH` for custom templates and wallpapers *pro* | | 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) | | PHOTOPRISM_USERS_QUOTA | --users-quota | 0 | maximum `NUMBER` of active user accounts, excluding guests (0 for unlimited) *pro* | ### 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 *pro* | | PHOTOPRISM_DISABLE_VECTORS | --disable-vectors | false | disables vector graphics support *pro* | | 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_THEME_URL | --theme-url | | download `URL` for installing a custom theme if none is installed *portal* | | 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 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` | | 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 | ### Cluster Configuration | Environment | CLI Flag | Default | Description | |:--------------------------------------|:-----------------------------|:--------------------------------------------|:---------------------------------------------------------------------------------------------------| | PHOTOPRISM_CLUSTER_DOMAIN | --cluster-domain | | cluster `DOMAIN` (lowercase DNS name; 1–63 chars) | | PHOTOPRISM_CLUSTER_CIDR | --cluster-cidr | | cluster `CIDR` for IP-based authorization, e.g. 10.0.0.0/8 | | PHOTOPRISM_CLUSTER_UUID | --cluster-uuid | | cluster `UUID` (v4) to scope node credentials | | PHOTOPRISM_CLUSTER_OIDC | --cluster-oidc | false | use the cluster Portal as this instance's OIDC login provider | | PHOTOPRISM_PORTAL_URL | --portal-url | https://portal.${PHOTOPRISM_CLUSTER_DOMAIN} | base `URL` of the cluster management portal | | PHOTOPRISM_JOIN_TOKEN | --join-token | | secret `TOKEN` required to join a cluster; min 24 chars | | PHOTOPRISM_NODE_NAME | --node-name | | node `NAME` (unique in cluster domain; [a-z0-9-]{1,32}) | | PHOTOPRISM_NODE_ROLE | --node-role | | node `ROLE` (instance or service) | | PHOTOPRISM_NODE_UUID | --node-uuid | | node `UUID` (v7) that uniquely identifies this instance | | PHOTOPRISM_NODE_CLIENT_ID | --node-client-id | | node OAuth client `ID` (auto-assigned via join token) | | PHOTOPRISM_NODE_CLIENT_SECRET | --node-client-secret | | node OAuth client `SECRET` (auto-assigned via join token) | | PHOTOPRISM_JWKS_URL | --jwks-url | | JWKS endpoint `URL` provided by the cluster portal for JWT verification | | PHOTOPRISM_JWKS_CACHE_TTL | --jwks-cache-ttl | 300 | JWKS cache lifetime in `SECONDS` (default 300, max 3600) | | PHOTOPRISM_JWT_SCOPE | --jwt-scope | config cluster vision metrics mcp users | allowed JWT `SCOPES` (space separated). Leave empty to accept defaults | | PHOTOPRISM_JWT_LEEWAY | --jwt-leeway | 60 | JWT clock skew allowance in `SECONDS` (default 60, max 300) | | PHOTOPRISM_PORTAL_OIDC_ISSUER | --portal-oidc-issuer | | Portal OIDC OP issuer `URL` advertised in discovery and ID tokens (defaults to site-url) | | PHOTOPRISM_PORTAL_OIDC_TTL | --portal-oidc-ttl | 300 | Portal OIDC OP access/ID-token lifetime in `SECONDS` (default 300, max 900) | | PHOTOPRISM_PORTAL_OIDC_CODE_TTL | --portal-oidc-code-ttl | 60 | Portal OIDC OP authorization-code lifetime in `SECONDS` (default 60, max 300) | | PHOTOPRISM_PORTAL_OIDC_DEFAULT_POLICY | --portal-oidc-default-policy | chooser | Portal OIDC OP routing policy when a user has access to multiple instances (`chooser` or `direct`) | | PHOTOPRISM_ADVERTISE_URL | --advertise-url | | advertised `URL` for intra-cluster calls (scheme://host[:port]) | ### 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 *pro* | | 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) *pro* | | PHOTOPRISM_STS_SUBDOMAINS | --sts-subdomains | false | applies rule to all subdomains *pro* | | PHOTOPRISM_STS_PRELOAD | --sts-preload | false | allows submission to Google's HSTS preload service *pro* | | PHOTOPRISM_REQUEST_LIMIT | --request-limit | 500 | maximum number of concurrent HTTP `REQUESTS` allowed from a single IP *pro* | | PHOTOPRISM_REQUEST_INTERVAL | --request-interval | 5ms | average `DURATION` between HTTP requests from a single IP (0-1000ms) *pro* | | PHOTOPRISM_AUTH_LIMIT | --auth-limit | 60 | maximum number of consecutive invalid access `TOKENS` from a single IP *pro* | | PHOTOPRISM_AUTH_INTERVAL | --auth-interval | 10s | average `DURATION` between invalid access tokens from a single IP (0-86400s) *pro* | | PHOTOPRISM_LOGIN_LIMIT | --login-limit | 10 | maximum number of consecutive failed `LOGINS` from a single IP *pro* | | PHOTOPRISM_LOGIN_INTERVAL | --login-interval | 1m0s | average `DURATION` between failed logins from a single IP (0-86400s) *pro* | | PHOTOPRISM_IPS_LIMIT | --ips-limit | 3 | maximum number of malicious request `ATTEMPTS` before a client IP is blocked (-1 to disable) *pro* | | PHOTOPRISM_IPS_INTERVAL | --ips-interval | 1h0m0s | average `DURATION` between malicious request attempts from a single IP (0-86400s) *pro* | | PHOTOPRISM_HTTP_CSP | --http-csp | | HTTP Content-Security-Policy (CSP) `HEADER` *pro* | | PHOTOPRISM_HTTP_CTO | --http-cto | nosniff | HTTP X-Content-Type-Options `HEADER` *pro* | | PHOTOPRISM_HTTP_COOP | --http-coop | same-origin | HTTP Cross-Origin-Opener-Policy (COOP) `HEADER` *pro* | | PHOTOPRISM_HTTP_REFERRER_POLICY | --http-referrer-policy | same-origin | HTTP Referrer-Policy `HEADER` *pro* | | PHOTOPRISM_HTTP_FRAME_OPTIONS | --http-frame-options | DENY | HTTP X-Frame-Options `HEADER` *pro* | | 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 *pro* | ### 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` *pro* | | 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® Portal Knowledge Base](/portal/kb/) - [PhotoPrism® User Guide](https://docs.photoprism.app/user-guide/) - [PhotoPrism® Knowledge Base](/kb/) - [PhotoPrism® Pro Knowledge Base](/pro/kb/) --- # File Format Support URL: https://www.photoprism.app/pro/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, .mp.jpeg, .mp.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® Pro Knowledge Base](/pro/kb/) --- # Firewall Settings URL: https://www.photoprism.app/pro/kb/firewall/ > Configuring Your Firewall to Work With PhotoPrism® Pro ## Incoming Requests Unless you have changed the default configuration or use a reverse proxy, PhotoPrism® Pro is reachable via port 2342 on all network devices. If you are using a firewall, please ensure that this port can be accessed from other computers on your network, or that your instance can be accessed [through a reverse proxy](https://docs.photoprism.app/getting-started/proxies/traefik/): Network Diagram ## 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. View Privacy Policy chevron_right View Compliance FAQ chevron_right 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. View examples chevron_right #### 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. Learn more chevron_right #### 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 (`-photoprism-secrets`). - When supplying custom database credentials, prefer Kubernetes secrets and keep values out of chart manifests. - SQLite is suitable for quick tests; production deployments should use MariaDB/MySQL with regular backups. ## Getting Support Commercial support is available with our Starter, Business, and Enterprise team plans: - - ## 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/) --- # LDAP and Active Directory URL: https://www.photoprism.app/pro/kb/ldap/ > Authenticating Users Against a Directory Server PhotoPrism® Pro lets you authenticate users against a central [Lightweight Directory Access Protocol (LDAP)](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. See [Environment Variables and CLI Flags](/pro/kb/config-options/) for more information on the configuration options. ## Config Options | Environment | CLI Flag | Default | Description | |--------------------------------|-----------------------|-------------------|----------------------------------------------------------------------------------------------| | PHOTOPRISM_LDAP_URI | --ldap-uri | | LDAP directory `URI`, e.g. ldaps://example.com:636 for LDAP over SSL/TLS | | PHOTOPRISM_LDAP_CERT | --ldap-cert | | LDAP directory SSL/TLS certificate `FILENAME` (.pem) | | PHOTOPRISM_LDAP_INSECURE | --ldap-insecure | false | skips SSL/TLS certificate verification when using LDAPS | | PHOTOPRISM_LDAP_CHASE | --ldap-chase | false | automatically chases referrals when there are multiple LDAP servers | | PHOTOPRISM_LDAP_CHASE_INSECURE | --ldap-chase-insecure | false | skips SSL/TLS certificate verification when chasing referrals | | PHOTOPRISM_LDAP_SYNC | --ldap-sync | false | updates name, email, role, and attributes from LDAP directory on login | | PHOTOPRISM_LDAP_BIND | --ldap-bind | simple | LDAP authentication `TYPE` (simple, md5) | | PHOTOPRISM_LDAP_BIND_DN | --ldap-bind-dn | userprincipalname | LDAP username attribute `DN`, e.g. cn or userprincipalname | | PHOTOPRISM_LDAP_BASE_DN | --ldap-base-dn | | LDAP directory base `DN`, e.g. dc=example,dc=com | | PHOTOPRISM_LDAP_ROLE | --ldap-role | | LDAP default `ROLE` (admin, manager, user, viewer, contributor, guest), leave blank for none | | PHOTOPRISM_LDAP_ROLE_DN | --ldap-role-dn | | custom LDAP group or attribute `DN` for specifying the role | | PHOTOPRISM_LDAP_NOLOGIN | --ldap-nologin | false | disables web login for new LDAP users by default | | PHOTOPRISM_LDAP_NOLOGIN_DN | --ldap-nologin-dn | | custom LDAP attribute `DN` to disable web login | | PHOTOPRISM_LDAP_WEBDAV | --ldap-webdav | false | allows new LDAP users to use WebDAV when they have a role that allows it | | PHOTOPRISM_LDAP_WEBDAV_DN | --ldap-webdav-dn | | custom LDAP attribute `DN` to enable WebDAV access | | PHOTOPRISM_LDAP_BASE_PATH_DN | --ldap-base-path-dn | | user base path LDAP attribute `DN` | | PHOTOPRISM_LDAP_UPLOAD_PATH_DN | --ldap-upload-path-dn | | user upload path LDAP attribute `DN` | | PHOTOPRISM_DISABLE_LDAP | --disable-ldap | false | disables authentication via LDAP | > [!NOTE] > Attributes in LDAP are not case sensitive, so it doesn't matter if you use upper or lower case for them in the configuration. ### Docker Compose Example ``` services: photoprism: ... environment: ## LDAP Authentication PHOTOPRISM_LDAP_URI: "ldaps://ldap.example.com:636" PHOTOPRISM_LDAP_INSECURE: "false" PHOTOPRISM_LDAP_SYNC: "true" PHOTOPRISM_LDAP_BIND: "simple" PHOTOPRISM_LDAP_BIND_DN: "userprincipalname" PHOTOPRISM_LDAP_BASE_DN: "dc=example,dc=com" PHOTOPRISM_LDAP_ROLE: "" PHOTOPRISM_LDAP_ROLE_DN: "ou=photoprism-*,ou=groups,dc=example,dc=com" PHOTOPRISM_LDAP_NOLOGIN: "false" PHOTOPRISM_LDAP_WEBDAV: "true" ``` ### Server URI & Certificate The URI of the LDAP or Active Directory server must be specified in the format `ldap://hostname:port` for plain LDAP and `ldaps://hostname:port` for LDAPS (LDAP over SSL). For this, the default ports are 389 (LDAP) and 636 (LDAPS). If the directory server does not have a certificate signed by a trusted certificate authority, you can either set `PHOTOPRISM_LDAP_INSECURE` to true to ignore SSL certificate errors, or trust a self-signed certificate by specifying a `.pem` file in the `/config/certificates` *storage* folder with `PHOTOPRISM_LDAP_CERT`. ### User Bind DN The *Bind DN* (Distinguished Name) is used to identify your account when you authenticate through the LDAP/AD directory server. PhotoPrism also uses it in combination with the *Base DN* to retrieve and synchronize user attributes such as the email address, display name, and role, if specified. It is usually set to the Common Name (CN) of the account or the [UPN (UserPrincipalName)](https://social.technet.microsoft.com/wiki/contents/articles/52250.active-directory-user-principal-name.aspx) in Active Directory, which is an email-like identifier such as `user@example.com`. However, UPNs don't necessarily require a valid domain. ### Directory Base DN The *Base DN* is the starting point when searching for users within the directory. It is commonly set to the domain components (DC) of your organization, for example `dc=example,dc=com`. ### Specifying User Roles The default role for users authenticated via LDAP/AD can be specified with `PHOTOPRISM_LDAP_ROLE`. You can additionally specify a custom role attribute with `PHOTOPRISM_LDAP_ROLE_DN`, for example `photoprismrole`. To indicate the role, you can then map the attribute to the name of a valid role in lowercase, for example `photoprismrole="viewer"`. Note that the attribute name is not case sensitive, but the values should be lowercase, e.g. `admin`, `true` or `false`. Alternatively, you can specify a group DN in `PHOTOPRISM_LDAP_ROLE_DN` and use `*` as a placeholder for the role name, e.g. `ou=photoprism-*,ou=groups,dc=example,dc=com`. Learn more chevron_right ### Custom Attributes Additional custom user attributes can be specified with the `PHOTOPRISM_LDAP_NOLOGIN_DN`, `PHOTOPRISM_LDAP_WEBDAV_DN`, `PHOTOPRISM_LDAP_BASE_PATH_DN` and `PHOTOPRISM_LDAP_UPLOAD_PATH_DN` config options. Note that attribute names are not case sensitive in LDAP. Instead of only providing an attribute name in `PHOTOPRISM_LDAP_NOLOGIN_DN` and `PHOTOPRISM_LDAP_WEBDAV_DN`, you can alternatively specifiy a key and value like `primaryGroupID=500`. > [!NOTE] > If no custom attribute has been configured or the attribute value is empty, the default will be used. ## Command-Line Tools ### Troubleshooting To test the connection to your LDAP/AD server, view user attributes, and troubleshoot problems, you can use the built-in `ldap search` subcommand, as shown in this example: ``` docker compose exec photoprism photoprism ldap search -D bob@example.com cn=bob ``` Users of **Red Hat-based Linux distributions** can substitute Docker with [Podman](https://podman.io/): ``` podman-compose exec photoprism photoprism ldap search -D bob@example.com cn=bob ``` You can combine it with these flags to change the output format, the maximum number of search results and the credentials used for authentication: | 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) | | `-b DN` | LDAP/AD directory base DN to search e.g. dc=example,dc=com | | `-D DN` | the DN to use to bind to the directory server when performing simple authentication | | `-w PASSWORD` | the PASSWORD to use to bind to the directory server when performing simple authentication | If you need additional authentication or query options, we recommend using the [freely available `ldapsearch` command](https://docs.ldap.com/ldap-sdk/docs/tool-usages/ldapsearch.html), which is included in most Unix-like operating systems as part of the LDAP utilities package. User accounts authenticated with LDAP/AD can be searched with the following command: ``` docker compose exec photoprism photoprism ldap ls ``` ### Viewing the Current Config Values To view the current values of all config options, you can run the following: ``` docker compose exec photoprism photoprism show config ``` To display all supported config options and their default values: ``` docker compose exec photoprism photoprism show config-options ``` > [!NOTE] > Note that 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. > [!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). ## 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/) --- # Managing User Accounts URL: https://www.photoprism.app/pro/kb/roles/ > Get an overview of the user account roles and management capabilities available in PhotoPrism® Pro. ## Roles and Permissions | Role | View Shared | View Private | View Library | Download | Upload | WebDAV | User Management | |-------------|:------------------------------------:|:------------------------------------:|:------------------------------------:|:------------------------------------:|:------------------------------------:|:--------:|:------------------------------------:| | admin | | | | | | optional | | | manager | | | | | | optional | restricted | | user | | | | | | optional | | | viewer | | | except private | except private | | | | | contributor | | | uploaded | shared & uploaded | upload path | optional | | | guest | | | | shared | | | | | visitor | | | | shared | | | | > [!NOTE] > Please note that this overview only applies to [PhotoPrism® Pro](https://www.photoprism.app/teams/#compare). Information on the user management features of [our personal editions](https://www.photoprism.app/editions/#compare) is available in the user guide at . ### Admin *Admins* have unrestricted access to all pictures, albums, and settings. Regular *Admins* can lose their privileges due to an intentional or accidental role change. However, accounts with the optional "superadmin" status (can be set with the `-s` flag) retain their admin privileges even if they are assigned a non-admin or invalid role. This is to prevent them from locking themselves out. When *Super Admins* change settings such as the language or theme, these automatically become the default settings for other users, unless they have explicitly made a different choice. In addition, global feature flags can only be changed by *Super Admins*. ### Manager The *Manager* role is similar to the *User* role, except that managers additionally have read-only access to the User Management tab in the [Admin Web UI](#admin-web-ui). This allows them to see which users have access to a PhotoPrism instance without being able to change user account roles or elevate account privileges. Managers can also audit and delete sessions through the web interface to prevent abuse and unauthorized access. ### User *Users* have full access to the library and can view, edit, and delete all pictures and albums. Unlike *Admins*, *Users* cannot view or change the [Library](https://docs.photoprism.app/user-guide/settings/library/) and [Advanced Settings](https://docs.photoprism.app/user-guide/settings/advanced/), only personal preferences such as theme, language, and password. In addition, their WebDAV access can be disabled. Future releases may include more ways to customize user privileges, e.g. with individual account attributes. ### Viewer *Viewers* are similar to regular *Users*, except that they do not have write access to the library and cannot see content that has been archived or marked private. They also cannot upload/import files or trigger indexing. Like all registered users, *Viewers* can change and save personal preferences such as theme, language, and password. ### Contributor *Contributors* 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 via a link (see below). 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. *Contributors* can also change their personal user preferences such as theme, language, and password. ### Guest *Guests* do not have access to the entire library. They only have read access (view and download) to the resources that are in their configured base path (if any) and to the resources that other users have shared with them, e.g. via a link. *Guests* can also change personal settings such as theme, language, and password. ### Visitor *Visitors* cannot be added manually. This special role is tied to a system account that represents anonymous users who use links to view albums or other content that has been shared with them. Visitors can only access these resources and cannot log in with a username or password. They also cannot retain their personal settings for longer than their browsing session lasts. > [!NOTE] > Our team will be happy to provide you with configuration recommendations and information about customization options. ## Sharing Between Users To share resources e.g. with *Guests* or *Contributors* who do not have full access, *Admins* and *Users* can [create share links](https://docs.photoprism.app/user-guide/share/). When a user with limited privileges opens such a link while being logged in, their account will get read-only access to the shared resources. It will later also be possible to share content with other users directly through the web interface without creating links first. ## Managing User Accounts ### 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 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//` paths, so you do not need a separate proxy or a certificate per instance. ## Cluster Architecture A cluster consists of one Portal and one or more *nodes*. Each node has a role: - **`instance`** — a regular PhotoPrism® instance that serves photos to end users. - **`service`** — a supporting service node (for example, a shared computer-vision worker) that is not a user-facing instance. The Portal itself is also a node, with the reserved `portal` role. Nodes never talk to each other directly; they communicate only with the Portal over HTTPS, authenticated with credentials issued when they join the cluster. You can run a cluster in one of two network layouts: | Layout | How it works | When to choose it | |------------------------|------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | **Separate hostnames** | Every instance has its own hostname and TLS certificate (e.g. `acme.example.com`). | Maximum isolation between instances; strict per-host separation of cookies and storage. | | **Shared domain** | The Portal proxies instances under one hostname via `/i//` paths. | Fewer certificates and DNS entries, a single entry point, and simpler testing. | See [Shared Domain Routing](#shared-domain) for details on the second option. ## Requirements - A dedicated hostname for the Portal (for example, `portal.example.com`) reachable by all instances. - [HTTPS with valid certificates](/pro/kb/https/) on the Portal and on every public instance — secure connections are a strict requirement for single sign-on. Instances may talk to the Portal over plain HTTP only on a trusted, cluster-internal network. - A MariaDB server the Portal can use to provision per-instance databases (when you want the Portal to manage instance databases automatically). - A lowercase DNS *cluster domain* (1–63 characters per label) that identifies the cluster and is used to derive default URLs. ## Setting Up the Portal The Portal is started from the `photoprism/portal` Docker image. At a minimum it needs the cluster domain and, if it should provision instance databases, an administrative database connection: ``` services: portal: image: photoprism/portal:latest environment: PHOTOPRISM_SITE_URL: "https://portal.example.com/" PHOTOPRISM_CLUSTER_DOMAIN: "example.com" ## Administrative database connection used to create per-instance ## databases and users (kept on the Portal only): PHOTOPRISM_DATABASE_PROVISION_DSN: "root:[admin-password]@tcp(mariadb:3306)/" ... ``` When the Portal starts for the first time, it creates a superadmin account and generates a *join token* that instances use to register (see [Adding Instances](#adding-instances)). The Portal acts as the cluster's [identity provider](/pro/kb/openid-connect/#cluster-authentication) out of the box; the issuer URL and token lifetimes can be tuned with the `PHOTOPRISM_PORTAL_OIDC_*` [config options](/pro/kb/config-options/#cluster-configuration). > [!NOTE] > Provisioned databases and users are named automatically from the cluster and node identifiers, with a configurable prefix (`PHOTOPRISM_DATABASE_PROVISION_PREFIX`, default `cluster_`). The administrative connection is used only to create and rotate these credentials and is never shared with instances. For Kubernetes deployments, the [`photoprism-pro` Helm chart](/pro/kb/helm-chart/) can register instances with a Portal automatically. See [Getting Started with Rancher and Kubernetes](/pro/kb/kubernetes/) for cluster networking and firewall requirements. ## Adding Instances Instances join the cluster by registering with the Portal using the *join token*. Registration is **idempotent** and safe to repeat on every start: a new instance receives its credentials on first boot, and an existing instance simply confirms its registration. ### Zero-Touch Registration The recommended approach is to let each instance register itself on startup. Provide the cluster domain, the Portal URL, and the join token as environment variables, and the instance registers automatically the first time it boots and on every restart: ``` services: photoprism: image: photoprism/pro:latest environment: PHOTOPRISM_CLUSTER_DOMAIN: "example.com" PHOTOPRISM_PORTAL_URL: "https://portal.example.com/" PHOTOPRISM_JOIN_TOKEN: "[join-token]" PHOTOPRISM_NODE_ROLE: "instance" PHOTOPRISM_NODE_NAME: "acme" PHOTOPRISM_SITE_URL: "https://acme.example.com/" ... ``` If `PHOTOPRISM_NODE_NAME` is omitted, the instance derives a name from its hostname. If `PHOTOPRISM_PORTAL_URL` is omitted, it defaults to `https://portal.`. The join token must be at least 24 characters long. > [!NOTE] > On first boot the instance receives its own OAuth credentials from the Portal, and — when it uses a MariaDB database without existing credentials — a provisioned database. Database changes require a restart to take effect. The instance never migrates an existing SQLite database to MariaDB automatically. ### Registering from a Terminal You can also register a node explicitly with the [`photoprism cluster register`](/pro/kb/cluster-cli/#register) command, for example to preview the request or to write the returned credentials to the local configuration: ```bash photoprism cluster register --name acme --role instance --write-config ``` [Learn more ›](/pro/kb/cluster-cli/) ## Shared Domain Routing Instead of giving every instance its own hostname, the Portal can serve them all under a single domain and forward requests based on the first path segment: ``` https://media.example.com/i/acme/ https://media.example.com/i/contoso/ ``` The Portal resolves the name after `/i/` to the matching instance and proxies the request to it. Unknown names return a generic *not found* response so the cluster does not reveal which instances exist. To use shared-domain routing: 1. Enable path routing on the Portal (`PHOTOPRISM_PORTAL_PROXY: "true"`; the path prefix defaults to `/i/` and can be changed with `PHOTOPRISM_PORTAL_PROXY_URI`). 2. Register each instance with a unique name and set its `PHOTOPRISM_SITE_URL` to the matching path, for example `https://media.example.com/i/acme/`. 3. Point each instance's advertise URL at an address the Portal can reach internally. > [!NOTE] > Because all instances share one origin in this layout, browser cookies and storage are scoped per instance path. For the strictest isolation between instances, use separate hostnames instead. ## Theme & Branding Sync The Portal stores a single branding theme (logos, colors, login background) and distributes it to instances. On startup, each instance compares its installed theme with the Portal's version and downloads the current theme when it is missing or out of date, so a branding change made once on the Portal propagates across the cluster. Administrator customizations made directly on an instance are preserved. You can also pull the theme on demand with [`photoprism cluster theme pull`](/pro/kb/cluster-cli/#theme). ## Managing the Cluster Once the cluster is running, you manage it from the Portal: - **Web interface** — the Portal management UI lists registered instances, lets you edit their details, and manages which users can access which instances. - **Command line** — the [`photoprism cluster` commands](/pro/kb/cluster-cli/) cover registration, listing and inspecting nodes, rotating credentials, granting user access, and theme distribution. For how users sign in and how access to instances is granted, see [Cluster Authentication & Access Control](/pro/kb/openid-connect/#cluster-authentication). ## 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/) --- # Portainer Setup Guide URL: https://www.photoprism.app/pro/kb/portainer/ > 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. ## Step 1: Create Application Stack ## Navigate to "Stacks", click "Add stack" and paste the [contents of our *stack.yml* config template](https://setup.photoprism.app/pro/portainer/stack.yml) into the *Web editor* so that you can change the storage folder locations in the `volumes` sections as needed: Screenshot 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 ## Screenshot 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: Screenshot 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 ****. > [!NOTE] > If you have modified the server hostname, port, or protocol in your configuration, the URL to use changes accordingly. ## Getting Started ## Our [First Steps 👣](https://docs.photoprism.app/user-guide/first-steps/) tutorial guides you through the user interface and settings to ensure your library is indexed according to your individual preferences. > [!NOTE] > The config options and container image you want to use can be changed at any time by navigating to "Stacks", selecting your existing PhotoPrism stack, clicking "Editor", updating the [configuration to your needs](/pro/kb/config-options/), and then clicking "Update the stack" to apply the changes. ## Activating Your License ## You can activate [your license](https://www.photoprism.app/pro/kb/activation/) by logging in with the [admin user created during setup](#step-2) and then following the steps [described in our activation guide](https://www.photoprism.app/pro/kb/activation/). [Learn more ›](https://www.photoprism.app/pro/kb/activation/) ## Command-Line Interface ## ### Opening a Terminal Navigate to "Stacks", select the PhotoPrism stack and scroll down to the list of containers: Screenshot 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: Screenshot 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. View Compliance FAQ chevron_right ### 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. Learn more chevron_right ## 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. Learn more chevron_right ## 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. Learn more chevron_right ## 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 ``` Learn more chevron_right **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. Configure Volumes chevron_right View Config Options chevron_right 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. Get Support chevron_right > [!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! Learn more chevron_right ### 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. Learn more chevron_right #### 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. Learn more chevron_right #### Using Audit Logs #### Audit logs help your security, auditing, and compliance entities monitor PhotoPrism® Pro for potential vulnerabilities, misuse, and other critical incidents. Learn more chevron_right #### 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. Learn more chevron_right ## 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) iPhone screenshot of the cards search result view 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): ![Edit Account](oidc-subject.jpg) 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: - Entra group claims: - Entra app roles: - Group overage handling: - Token customization guidance: ## Cluster Authentication & Access Control When you run multiple instances behind a [PhotoPrism® Portal](/pro/kb/portal/), the Portal can act as the central [identity provider](#identity-providers) for the whole cluster: users sign in once at the Portal, and the Portal then logs them in to the instances they are allowed to use. Each instance is an OpenID Connect client of the Portal, so the [single sign-on flow](#identity-providers) described above is reused unchanged — only the issuer is the Portal instead of an external provider. ### Enabling Portal Login on an Instance Set `PHOTOPRISM_CLUSTER_OIDC` to `"true"` on an instance to use the Portal as its login provider. The instance then derives its OpenID Connect client ID and secret from the node credentials it received when it [joined the cluster](/pro/kb/portal/#adding-instances) and defaults the [Issuer URI](#issuer-uri) to the Portal, so no manual `PHOTOPRISM_OIDC_URI`, `PHOTOPRISM_OIDC_CLIENT`, or `PHOTOPRISM_OIDC_SECRET` is required: ``` services: photoprism: ... environment: PHOTOPRISM_CLUSTER_DOMAIN: "example.com" PHOTOPRISM_PORTAL_URL: "https://portal.example.com/" PHOTOPRISM_CLUSTER_OIDC: "true" PHOTOPRISM_OIDC_REGISTER: "true" ``` > [!NOTE] > Explicitly configured `PHOTOPRISM_OIDC_URI`, `PHOTOPRISM_OIDC_CLIENT`, and `PHOTOPRISM_OIDC_SECRET` values always take precedence over the automatic derivation, so you can still point an instance at a different provider if needed. `PHOTOPRISM_OIDC_REGISTER` must be `"true"` for users authorized by the Portal to create their account on the instance at first login. After signing in at the Portal, users with access to a single instance are redirected straight to it, while users with access to more than one instance are shown an **instance chooser** and pick where to go. ### Access Is Closed by Default A user who can authenticate at the Portal is **not** automatically able to open any instance. Access to each instance must be granted explicitly, and it is re-evaluated on every login, so removing a user's access takes effect the next time they sign in. There are two ways to grant access, and a user is admitted if **either** applies (when both apply, the highest-privilege role wins): 1. **Per-user assignments.** A cluster administrator assigns a user to an instance — with a specific role or the user's default account role — in the Portal management interface, or from a terminal: ```bash photoprism cluster users access grant --user [user-uid] --node [node-uuid] --role viewer ``` [Learn more ›](/pro/kb/cluster-cli/#users) 2. **Security groups.** Membership in an [Entra ID or other security group](#security-groups) admits the user to the instances mapped to that group, with a role derived from the group. Each instance declares which groups it admits, either in its configuration or centrally in the Portal: | Environment | CLI Flag | Description | |--------------------------------------|-----------------------------|------------------------------------------------------------------------------------| | PHOTOPRISM_CLUSTER_ALLOW_GROUPS | --cluster-allow-groups | admit one or more group `ID`s to this instance via the Portal (repeat to add more) | | PHOTOPRISM_CLUSTER_ALLOW_GROUP_ROLES | --cluster-allow-group-roles | map `GROUP=ROLE` for admission to this instance (repeat to add more) | | PHOTOPRISM_CLUSTER_GROUPS_FULL_VIEW | --cluster-groups-full-view | also send the user's full group set to this instance, not only the matched groups | ### Cluster Roles The roles a user receives **on an instance** are the regular PhotoPrism® [user roles](/pro/kb/roles/) (`admin`, `manager`, `user`, `viewer`, `contributor`, `guest`), assigned per instance through the grants and group mappings above. The separate `cluster_admin` role applies **only** to the Portal: it grants access to the cluster management interface and the [`photoprism cluster` commands](/pro/kb/cluster-cli/). For security reasons, `cluster_admin` is never assigned through an external identity provider or security group, and it does not by itself grant access to any instance — a cluster administrator who also needs to use an instance must be assigned to it like any other user. > [!NOTE] > Support for running a Portal-managed cluster is only available with our [team plans](/teams/#compare), not the [personal editions](/editions/#compare). ## Frequently Asked Questions ### Can I configure a custom claim for the preferred username? You can choose between `preferred_username`, `name`, `nickname` and verified[^2] `email`, where `preferred_username` is the default. The other claims are used as fallback if no value is returned for the [configured claim](#config-options). Please note that it is currently not possible to use [other standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) or non-standard claims, as these may not be [suitable for generating a username](#preferred-username) and [no logic is implemented](https://github.com/photoprism/photoprism/blob/develop/internal/auth/oidc/username.go) for doing so. [Learn more ›](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) ### What if my provider does not return any claims for generating a username? Certified [OIDC Identity Providers](#identity-providers), as well as public service providers such as [Google](https://developers.google.com/identity/openid-connect/openid-connect), should support (at least) a subset of the [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) that PhotoPrism can use to [generate a username](#preferred-username) for newly registered accounts. These are `preferred_username`, `name`, `nickname` and verified[^2] `email`, where `preferred_username` is the default. If only an unverified `email` address[^2] or none of [these claims](#can-i-configure-a-custom-claim-for-the-preferred-username) are returned, we recommend that you report this to the vendor of the [Identity Provider](#identity-providers) you are using, as this is also likely to cause problems with other software. In a future release, we may offer additional [config options](#config-options) to work around this issue, e.g. by generating a random username. However, this is currently not possible. [Learn more ›](#preferred-username) ## 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/) [^1]: `PHOTOPRISM_OIDC_REGISTER` must be set to `"true"` to allow new users to create an account via OpenID Connect. [^2]: The `email_verified` flag must be set by the [OIDC Identity Provider](#identity-providers) so that the `email` address can be used to send notifications and/or confirm the identity of users. If we do not insist on verification, this could otherwise have a negative impact on trust and security. [^3]: Admins are unable to change the authentication method of their own user account through the [Admin Web UI](https://docs.photoprism.app/user-guide/users/#editing-user-details), so they cannot accidentally lock themselves out e.g. by setting it to *None*. --- # System Requirements URL: https://www.photoprism.app/pro/kb/requirements/ > PhotoPrism® Pro Hard- and Software Compatibility **We recommend hosting PhotoPrism Pro on a server with at least 4 cores, 8 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 Pro 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. Get started chevron_right ## 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. When in doubt, we recommend to start with 8 cores and to scale up as needed. However, if you already know that high performance is crucial, you may want to start with 16 cores or more and adjust the amount of RAM accordingly. #### NAS Devices Entry-level NAS devices may not be suitable for running PhotoPrism, especially if their CPU is optimized for low power consumption. We recommend testing the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license. Learn more chevron_right ## 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. Learn more chevron_right ## 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 Pro 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. Learn more chevron_right ## 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. Learn more chevron_right ## 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: Network Diagram We recommend testing the performance with our freely available [Community Edition](/editions/#compare) before purchasing a commercial license. View config options chevron_right ## 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. Learn more chevron_right ## 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. Activate Your License chevron_right Get Support chevron_right > [!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. Learn more chevron_right ### 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. Learn more chevron_right ### Using Audit Logs ### Audit logs help your security, auditing, and compliance entities monitor PhotoPrism® Pro for potential vulnerabilities, misuse, and other critical incidents. Learn more chevron_right ### 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. Learn more chevron_right ## 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. Network Diagram ## 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 Bunny CDN 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 [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 [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. View examples chevron_right #### 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. Learn more chevron_right #### 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. Learn more chevron_right ## 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 ``` Troubleshooting chevron_right > [!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. Configure Volumes chevron_right View Config Options chevron_right 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. Connect Membership Account chevron_right Get Support chevron_right > [!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. Learn more chevron_right ## Session Monitoring Built-in reporting helps you monitor PhotoPrism® Plus for potential vulnerabilities, misuse, and other critical incidents. Learn more chevron_right ## Using HTTPS Our guide shows you how to enable transport encryption, add server certificates, and create new certificates. Learn more chevron_right ## 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. Get started chevron_right ## 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). Learn more chevron_right ## 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. Learn more chevron_right ## 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. Learn more chevron_right ## 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. Learn more chevron_right ## 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: Network Diagram We recommend testing the performance with our freely available [Community Edition](/editions/#compare). View config options chevron_right ## 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. Learn more chevron_right ## 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. Network Diagram ## 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 Bunny CDN 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.

Read the docs Whether you're using a phone, tablet, or desktop computer, our intuitive [Progressive Web App](https://try.photoprism.app/) makes it easy to browse your photo collection. It provides a native app-like experience, and you can easily install it on the home screen of all major operating systems and mobile devices. We recommend Docker for running your own server with our self-hosted [Community Edition](https://docs.photoprism.app/getting-started/). It is available for Mac, Linux and Windows. PhotoPrism also runs on [DigitalOcean](https://docs.photoprism.app/getting-started/cloud/digitalocean/), [Raspberry Pi](https://docs.photoprism.app/getting-started/raspberry-pi/), [FreeBSD](https://docs.photoprism.app/getting-started/freebsd/), and many [NAS devices](https://docs.photoprism.app/getting-started/nas/synology/). Quickly find specific photos and videos with powerful search filters. To make this possible, your files are [automatically classified](https://try.photoprism.app/library/labels), [stacked if they belong together](https://docs.photoprism.app/user-guide/organize/stacks/), and [enriched with location details](https://docs.photoprism.app/user-guide/organize/edit/#details) during [indexing](https://docs.photoprism.app/user-guide/library/originals/). [Search filters](https://docs.photoprism.app/user-guide/search/filters/) can be combined and are available for [many different properties](https://docs.photoprism.app/user-guide/search/filters/#filter-reference), such as [label](https://try.photoprism.app/library/labels), location, resolution, color, chroma, and [quality](https://try.photoprism.app/library/review). By default, [exact duplicates](https://docs.photoprism.app/user-guide/library/duplicates/) and pictures marked as [private](https://docs.photoprism.app/user-guide/organize/private/), [archived](https://docs.photoprism.app/user-guide/organize/archive/), or [under review](https://docs.photoprism.app/user-guide/organize/review/) do not appear in search results, so you find only relevant content without screenshots or pictures you do not want to share. Our [latest version](https://docs.photoprism.app/release-notes/) includes [facial recognition](https://docs.photoprism.app/user-guide/organize/people/) that lets you find pictures of your family and friends. Be ready to discover long-forgotten shots! New faces are detected as you scan your library. They are then grouped by similarity, so you can quickly match them to people. The app includes [six high-resolution maps](https://try.photoprism.app/library/places) to bring back memories of your favorite trips and let you explore the world. In addition, our [privacy-preserving geocoding service](https://docs.photoprism.app/getting-started/#maps-places) provides you with worldwide location details to enrich your photos with information about where you have been. Future versions will also be able to use public event databases to automatically create albums of popular music festivals or sporting events. Secret links make it easy to share [albums](https://try.photoprism.app/library/albums) with your loved ones. 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. PhotoPrism supports indexing, viewing, and [converting](https://docs.photoprism.app/user-guide/settings/library/) 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](https://docs.photoprism.app/getting-started/faq/#what-media-file-types-are-supported), regardless of camera make and model. A full list of file types and extensions can be found in our [Knowledge Base](/kb/file-formats/). For maximum browser compatibility, video codecs and containers supported by [FFmpeg](https://en.wikipedia.org/wiki/FFmpeg#Supported_codecs_and_formats) can be transcoded to MPEG-4 AVC on demand, just as still images can be extracted for thumbnail creation. 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 and merged so that you can easily search and edit it through the user interface. Supported fields include _Title_, _Description_, _Date_, _Location_, _Camera_, _Lens_, _ISO_, _F Number_, _Exposure_, _Focal Length_, _Subject_, _Artist_, _Keywords_, and _Copyright_. Exact [duplicates are skipped](https://docs.photoprism.app/user-guide/library/duplicates/) when your library is scanned. Images that share a unique identifier, filename, or time and location can be automatically stacked together. Sidecar files are always [stacked with the associated media file](https://docs.photoprism.app/user-guide/organize/stacks/). Use [PhotoSync](https://link.photoprism.app/photosync) to securely backup iOS and Android phones in the background. WebDAV clients such as Microsoft's Windows Explorer and Apple's Finder can [connect](https://docs.photoprism.app/user-guide/sync/webdav/) directly to PhotoPrism, allowing you to open, edit, and delete files from your computer as if they were local. Because PhotoPrism is [100% self-funded and independent](/about/company/), we can promise you that we will never sell your data and that we will always be transparent about our software and services. Your data will also never be shared with Google, Amazon, Facebook, or Apple unless you intentionally upload files to one of their services. Teams and organizations get the same promise at scale: [Team Editions](/teams/) run fully on-premises and [GDPR-compliant](/privacy/gdpr/), so your media — and your users' data — stays in your own infrastructure, under your control. Our [Project Roadmap](https://link.photoprism.app/roadmap) shows what is in progress and what features will be implemented next. You are invited to give ideas you like a thumbs-up, so we know what's most popular. In addition to these features, our [Team Editions](/teams/) provide your organization with enhanced scalability, security, customization, and authentication capabilities. Compare Team Plans --- # Pricing & Editions URL: https://www.photoprism.app/editions/
Simple, affordable pricing. Upgrade or downgrade at any time.

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.

Get Started

--- # Team Editions URL: https://www.photoprism.app/teams/ > PhotoPrism® Pro is 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.
Simple, affordable pricing. Upgrade or downgrade at any time.

Starter

Business

business
21900 / mo

Enterprise

verified
from € 149900 / mo

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.

- SLA-backed Email and Chat [support](/pro/support/) with agreed response times, plus help with setup, configuration, and upgrades - [Single sign-on](/portal/kb/access-and-authentication/) via OpenID Connect (for example Microsoft Entra ID) and LDAP/Active Directory, with security-group role mapping - Hardened, regularly updated container images with TLS throughout and [security audit logs](/security-policy/) for user actions - On-premises multi-tenant [Portal cluster](/portal/kb/) that provisions, proxies, and authenticates many instances on Kubernetes or OpenShift - Fully [self-hosted](/pro/kb/), so your photos, videos, and metadata never leave your own infrastructure - A [commercial license](/pro/license/) with additional configuration options and the right to customize functionality to your needs

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.
Google Play Store Apple App Store
This Android app lets you conveniently browse the pictures in your library and share them with other apps. The app offers a timeline view, authentication, bookmarks, and many other useful features. It can also be installed on Android TV, so you can browse your library with a remote control.
Google Play Store Get it on F-Droid
---