Skip to content

Frequently Asked Questions

What media file types are supported?

PhotoPrism supports indexing, viewing, and converting most popular image, video and RAW formats, including JPEG, PNG, GIF, BMP, HEIF, HEIC, MP4, MOV, WebP, and WebM. TIFF is partially supported without extensions such as GeoTIFF.

When indexing, a JPEG or PNG sidecar file is automatically created for videos and images in other formats, such as RAW or vector graphics. It is needed for thumbnail generation, image classification, and face detection. JPEG XL support is planned as soon as it is generally available and enough compatible tools exist.

If installed, converting RAW files is possible with the following converters (our Docker image includes both):

On a Mac, RAW files can also be converted with Sips (supported cameras). Our goal is to provide top-notch support for all RAW formats, regardless of camera make and model. Please let us know about any issues with a particular camera or file format.

For maximum browser compatibility, video codecs and containers supported by FFmpeg can be transcoded to MPEG-4 AVC on demand, just as still images can be extracted for thumbnail creation.

Make sure you have JSON sidecar files enabled if you have videos, live photos, and/or animated GIFs so that video-specific metadata such as codec, frames, and duration can be extracted, indexed, and searched.

For a complete list of file formats and extensions, see our downloadable Feature Overview.

In case FFmpeg is disabled or not installed, videos cannot be indexed because still images cannot be created. You should also have ExifTool enabled to extract metadata such as duration, resolution, and codec.

What are sidecar files and where do I find them?

A sidecar is a file that sits next to your main photo or video files and usually has the same name but a different extension:

  • IMG_0123.mov
  • IMG_0123.mov.jpg
  • IMG_0123.json

New sidecar files are saved in the storage folder by default, so the originals folder can be mounted read-only.

Even if PHOTOPRISM_DISABLE_EXIFTOOL is set to “true” or PHOTOPRISM_SIDECAR_YAML is set to “false”, the indexer will look for existing sidecar files and use them.

What metadata sidecar file types are supported?

Currently, three types of file formats are supported:

JSON

If not disabled via PHOTOPRISM_DISABLE_EXIFTOOL or --disable-exiftool, ExifTool is used to automatically create a JSON sidecar for each media file. In this way, embedded XMP and video metadata can also be indexed. Native metadata extraction is limited to common Exif headers. Note that this causes small amount of overhead when indexing for the first time.

JSON files can also be useful for debugging, as they contain the full metadata and can be processed with common development tools and text editors.

JSON files exported from Google Photos can be read as well. Support for more schemas may be added over time.

YAML

Unless disabled by setting the PHOTOPRISM_SIDECAR_YAML option to "false" in your configuration, PhotoPrism automatically creates/updates human-friendly YAML sidecar files during indexing and after manual editing of fields such as title, date, or location. They serve as a backup in case the database (index) is lost, or when folders are synchronized with a remote instance.

Like JSON, YAML files can be opened with common development tools and text editors. However, changes are not synchronized with the original index, as this could overwrite existing data.

XMP

XMP (Extensible Metadata Platform) is an XML-based metadata container format developed by Adobe. It provides many more fields (as part of embedded models like Dublin Core) than Exif. This also makes it difficult - if not impossible - to provide full support. Reading title, copyright, artist, and caption from XMP sidecar files is implemented as a proof-of-concept, contributions are welcome. Indexing of embedded XMP is only possible via ExifTool, see above.

Does your software depend on any external services?

As explained in our Privacy Policy, reverse geocoding and interactive world maps depend on retrieving the necessary information from us and MapTiler AG, 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. Depending on your usage, this can save you much more than the cost of a PhotoPrism+ Membership, 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.

View Privacy Policy › View Compliance FAQ ›

In order to successfully set up your installation and view location details in PhotoPrism, you must allow incoming requests as well as those to our Geocoding API and Docker if you have a firewall installed, and make sure that your Internet connection is working:

Why do I see connection errors when requesting API keys at startup?

Retrieving location data with reverse geocoding and loading the interactive world maps we provide requires a connection to external services. Please make sure that requests to these API endpoints are allowed if you have a firewall installed, and that your internet connection is working.

Learn more ›

Are the keys for using interactive world maps provided free of charge?

All users have access to a high-resolution vector map that we host on our own infrastructure, so no commercial API key is required. It is based on data published by OpenStreetMap (OSM).

In addition, we automatically provide our members and business customers with an API key for MapTiler's commercial service, which includes satellite, outdoor and 3D maps. You can test these on our public demo.

Learn more ›

Although experienced users could alternatively register test accounts with a commercial provider to gain access to additional map styles instead of signing up for a membership, we believe this would not be fair. Keep in mind that we have a much larger user base than others who might encourage their users to do so, and that providers might then stop offering free test accounts, which is something we don't want to be responsible for.

Why don't you use the free map tile service provided by OpenStreetMap?

Other free and open-source software sometimes uses the public maps that OpenStreetMap provides for development and testing. These are not intended for end-user applications like ours.

Using their service also means that their usage and privacy policies apply, as your request data is stored and used to generate publicly available reports. This differs from our services, which ensure a high level of privacy and provide a better user experience with faster loading times.

How can I activate my membership?

To connect a new instance to your membership account, you will need to log in with the super admin user that is automatically created during setup (see your compose.yaml or docker-compose.yml file or the app store documentation), and then follow the steps described in our activation guide.

View Activation Guide ›

What are the advantages of purchasing a commercial license?

A key difference between the public license and a commercial 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 compliance and scalability.

Compare Team Editions ›

Will the self-hosted version continue to be supported?

Absolutely! We are on a mission to protect your freedom and privacy. Self-hosting is the easiest way to stay in control and protect your privacy. It also provides the best experience for advanced users who often rely on a local toolchain to select, edit, and publish their pictures.

At the same time, we know there's a huge demand and many practical uses for a cloud-hosted app that is easy to set up. We like to give our users the choice and therefore offer a fully managed service as a deployment option. Selected hosting partners ensure that your privacy is protected as much as technically possible, even in the cloud.

JPEGs are currently not regenerated when related RAW or XMP files change. RAW files are digital negatives by design. PhotoPrism therefore assumes that their image information is immutable.

XMP files can affect the appearance, but most of the metadata they contain, such as title and caption, does not. Creating JPEGs from RAW files is a time-consuming task, and in most cases would cause a huge, unjustified amount of overhead. In addition, the rendering information in XMP files is not well standardized. For example, changes you make in Photoshop may not be compatible with Darktable.

We recommend manually updating existing JPEG sidecar files as needed or creating additional JPEGs, so you can choose between different versions. New files and other metadata changes are detected and reflected in the index as usual when your library is scanned.

Which folder will be indexed?

This depends on your environment and configuration. While sub folders can be selected for indexing in the UI, changing the originals base folder requires a restart for security reasons.

If you skip configuration and don't use one of our Docker images, PhotoPrism will attempt to find a photo library by searching a list of common folder names such as /photoprism/originals and ~/Pictures. It also searches for other resources such as external applications, classification models, and frontend assets.

If you use our Docker Compose example without modifications, pictures will be mounted from ~/Pictures where ~ is a shortcut for your home directory:

  • \user\username on Windows
  • /Users/username on macOS
  • and /root or /home/username on Linux

Since the app is running inside a container, you have to explicitly mount the host folders you want to use. PhotoPrism won't be able to see folders that have not been mounted. Multiple folders can be made accessible by mounting them as sub folders of /photoprism/originals, for example:

volumes:
  - "/home/username/Pictures:/photoprism/originals"
  - "/example/friends:/photoprism/originals/friends"
  - "/mnt/photos:/photoprism/originals/media"

Can I use FAT32 and ExFAT formatted drives?

Photos and videos can be mounted from FAT-formatted drives, such as an external SSD. Our tests have shown that PhotoPrism and MariaDB can also be started from there. However, at least on macOS, the logs may occasionally show directory access errors and you will be forced to restart if problems occur.

PhotoPrism depends on a number of other open source tools and applications, such as Darktable, RawTherapee, and FFmpeg. While you can install them directly on Windows, it's a lot of work and we don't have the capacity to test the respective Windows versions before each release.

We therefore recommend to use Docker, so you can take advantage of our pre-built and QA-tested Docker image, which includes all the dependencies you need. It is a well-tested standard tool that also lets you run many other self-hosted apps without having to worry about the details or Windows-specific issues. To further simplify the setup for you, we offer a batch script that you can run in the directory where you want to install PhotoPrism:

curl.exe -o install.bat https://dl.photoprism.app/docker/windows/install.bat
install.bat

This will automatically download all required config files and start the server for you. Before you run the script, make sure you have Docker Desktop installed on your Windows PC.

How can I install PhotoPrism without Docker?

Installation Packages

Experienced users can use the packages available at dl.photoprism.app/pkg/linux/ to install PhotoPrism on compatible Linux distributions, e.g. 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

Note that these packages must be updated manually, do not come with a default configuration, and do not include the system dependencies required to make use of all the features. The minimum required glibc version is 2.35, so for example Ubuntu 22.04 and Debian Bookworm will work, but older Linux distributions may not be compatible.

Learn more ›

Arch Linux Packages

Thomas Eizinger maintains AUR packages for installation on Arch Linux. These are based on the pre-built installation packages we provide and have a systemd integration so that PhotoPrism can be started and restarted automatically.

Learn more ›

LXC Images

There are currently no official LXC images available from us. However, you can use our installation packages together with the documentation we provide to set them up in a base image of your choice.

Since Docker and LXC are pretty much the same technology, you can also convert our Docker image to the LXC format, e.g. with the following commands:

apt update
apt install lxc umoci skopeo
lxc-create photoprism -t oci -- --url docker://photoprism/photoprism:latest

PhotoPrism can then be configured and started like any other LXC container:

lxc-start --name=photoprism -- /opt/photoprism/bin/photoprism start

Please note, though, that the network, storage and database configuration requires detailed knowledge of LXC. We therefore only recommend this approach if you can complete the setup without help from our documentation or support from our team.

BSD Ports

For FreeBSD and TrueNAS CORE (formerly FreeNAS) users, an unofficial port is available that builds PhotoPrism from source. It will also compile and install the required TensorFlow libraries for you.

Building From Source

You can alternatively build and install PhotoPrism from the publicly available source code, which includes all the Community Edition features and most of the Essentials features (except additional user roles):

git clone https://github.com/photoprism/photoprism.git
cd photoprism
make all install DESTDIR=/opt/photoprism

When choosing this installation method, missing build and system dependencies must be installed manually, as shown in our human-readable and versioned Dockerfiles. Since you often don't need to use the exact same versions, you can replace most packages with those available in your environment.

Please be aware, though, that we do not have the resources to provide support and special dependencies, such as TensorFlow libraries, to private users who choose to build from source. If possible, we recommend using Docker Compose or the installation packages we provide, as they can save a lot of time creating and troubleshooting custom builds.

PhotoPrism Plus

If you are a Plus, Silver, Gold or Platinum member and would like to build from source, please let us know so we can give you access to our private extension repository and provide assistance.

What are the benefits of using Docker?

(1) Docker uses standard features of the Linux kernel. Containers are nothing new; Solaris Zones were released about 20 years ago and the chroot system call was introduced during development of Version 7 Unix in 1979. It is used ever since for hosting applications exposed to the public Internet. Modern Linux containers are an incremental improvement of this, based on standard functionality that is part of the kernel.

(2) Docker saves time through simplified deployment and testing. A main advantage of Docker is that application images can be easily made available to users via Internet. It provides a common standard across most operating systems and devices, which saves our team a lot of time that we can then spend more effectively, for example, providing support and developing one of the many features that users are waiting for.

(3) Dockerfiles are part of the source code repository. Human-readable and versioned Dockerfiles that are part of our public source code help avoid "works for me" moments and other unwelcome surprises by enabling us to have the exact same environment everywhere in development, staging, and production.

(4) Running applications in containers is more secure. Last but not least, virtually all file format parsers have vulnerabilities that just haven't been discovered yet. This is a known risk that can affect you even if your computer is not directly connected to the Internet. Running apps in a container with limited host access is an easy way to improve security without compromising performance and usability.

A virtual machine with a dedicated operating system environment provides even more security, but usually has side effects such as lower performance and more difficult handling. Using a VM, however, doesn't prevent you from running containerized apps to get the best of both worlds. This is essentially what happens when you install Docker on virtual cloud servers and operating systems other than Linux.

What can I do if the Docker container fails with an S6 overlay error?

A container startup error similar to the following indicates that you are using a custom service configuration that is incompatible with our Docker images:

/package/admin/s6-overlay/libexec/preinit:
fatal: /run belongs to uid 0 instead of 100
and we're lacking the privileges to fix it.

In particular, this can happen if you have specified an unsupported user or group ID through the optional user property in your compose.yaml file to run the service, and at the same time added no-new-privileges to the security_opt section.

The supported ID ranges for running our container images are as follows:

  • UID: 0, 33, 50-99, 500-600, 900-1250, and 2000-2100
  • GID: 0, 33, 44, 50-99, 105, 109, 115, 116, 500-600, 900-1250, and 2000-2100

Please also check if you have specified both a user service property and the corresponding environment variables to set the user and/or group ID under which the "photoprism" service should run, as this is neither required nor recommended:

services:
  photoprism:
    user: "1000:1000"
    environment:
      PHOTOPRISM_UID: 1000
      PHOTOPRISM_GID: 1000

If you need maximum security and do not want to perform any additional startup actions that require root privileges, you can alternatively set the entrypoint and command for the "photoprism" service as follows:

services:
  photoprism:
    restart: unless-stopped
    entrypoint: ["/opt/photoprism/bin/photoprism"]
    command: ["start"]

The default entrypoint script can install additional distribution packages, fix file system permissions, and/or change the UID/GID for the "photoprism" service, as some NAS devices, for example, do not support this from their user interface. So, bypassing it as shown above will disable this functionality and is only recommended for advanced users who are familiar with running container services.

Learn more ›

If you are experiencing a similar problem with a custom configuration that we did not provide or recommend, please try changing it to see if that helps before asking our team or community members for support. 🛟

Why does your Docker image use the Plus License instead of the AGPL?

Our Plus License is used for both the extensions we provide to our members and the standard Docker images available on Docker Hub. This allows us to bundle the extensions with the compiled application, while the Community Edition remains freely available under the terms of the GNU Affero General Public License (AGPL).

If you don't plan to use any additional features, you can alternatively use the "ce" tag instead of "latest" to get a slightly smaller Docker image distributed under the AGPL. Note that system dependencies and other third-party components included in this image are still subject to additional terms and conditions.

View Open Source FAQ › View Plus License ›

Should I use SQLite, MariaDB, or MySQL?

PhotoPrism is compatible with SQLite 3 and MariaDB 10.5.12+. Official support for MySQL 8 has been discontinued as Oracle seems to have stopped shipping new features and enhancements.

If you only have few pictures, concurrent users, and CPU cores, SQLite may seem faster compared to full-featured database servers like MariaDB. This changes as the index grows and the number of concurrent accesses increases. While MariaDB is optimized for high concurrency, SQLite frequently locks its index so that other operations have to wait. In the worst case, this can lead to locking errors and timeouts during indexing - especially in combination with a slow disk or network storage.

The main advantage of SQLite is that you don't need to run a separate database server. It is therefore well suited for testing and can also be sufficient for small libraries with a few thousand files. If you are looking for scalability and high performance, it is not a good choice.

Is database corruption a common problem with self-hosting?

The likelihood of database corruption is generally very low if you follow our documentation. Our team runs many instances/databases and has never had any issues over the years.

However, if you run MariaDB or SQLite on a network drive or an external drive/stick that e.g. has been accidentally removed, it can happen. This is why our documentation explicitly warns about the danger of using unreliable storage for database files.

Some users also configure a named or anonymous Docker volume for the database, or mount the wrong path so that their index is lost when they recreate the database container, e.g. after an update of the Docker image.

I've configured an external database, but can't connect?

Most often this happens when new users configure localhost or 127.0.0.1 as database server host, since these always point back to the current container or computer. So it is not possible to access an external service with such a hostname or an IP address starting with 127. It works only if it is used directly in the container or on the computer where the database server is running. Instead, you must use a hostname or IP address that is accessible from other machines and containers.

Resolve Connection Issues ›

How can I determine the public IP address of my home network?

You can use one of the following services to view your public IP address, i.e. the IP address that the computers in your home network use to communicate with the Internet:

Why is my configured memory limit exceeded when indexing, even though PhotoPrism doesn't actually seem to use that much memory?

When indexing a media library, many files are opened and processed very quickly, which is not a typical workload compared to other containerized applications and services. Various libraries and external applications simultaneously interact with each other in complex ways, so a few spikes are inevitable. Some memory is also used by the kernel for buffered I/O to improve performance, although the extent to which caching counts towards a limit may vary.

We therefore recommend not to set a hard memory limit, unless you are familiar with memory management and understand the implications. Instead, you should reduce the number of indexing workers and limit file size and resolution if you are low on resources or want to limit memory usage for other reasons. Also make sure you have at least 4 GB of swap configured.

View System Requirements › Get Performance Tips ›

Why does PhotoPrism always consume 100% of CPU when the background worker is running?

Many users reporting poor performance and high CPU load have migrated from SQLite to MariaDB so that their database schema is not optimized for performance, for example, because indexes are missing or columns have the wrong data type. The instructions for these migrations were provided by a contributor and are not part of the original software distribution. As such, they have not been officially released, recommended, or extensively tested by us.

In some instances, users have manually changed the contents of the database. It is also possible that the database is in an inconsistent state for other reasons, e.g. due to bugs in previous versions that have been fixed in the meantime. However, we are not currently aware of any such cases.

Due to the amount of time required to review each report, we can only offer this to eligible members and business customers, and not to users who have chosen our free community edition.

Get Performance Tips › View Database Schema ›

Can you improve performance when using older or otherwise slow hardware?

It is a known issue that the user interface and backend operations, especially face recognition, can be slow or even crash on older hardware due to a lack of resources. Like most applications, PhotoPrism has certain requirements and our development process does not include testing on unsupported or unusual hardware.

In many cases, performance can be improved through optimizations. Since these can prove to be very time-consuming and cost-intensive in practice, users and developers must decide on a case-by-case basis whether this provides sufficient benefit in relation to the costs or whether the use of more powerful hardware is faster and cheaper overall.

We kindly ask you not to open a problem report on GitHub Issues for poor performance on older hardware until a full cause and feasibility analysis has been performed. GitHub Discussions or any of our other public forums and communities are great places to start a discussion.

That being said, one of the advantages of open-source software is that users can submit pull requests with performance and other enhancements they would like to see implemented. This will result in a much faster solution than waiting for a core team member to remotely analyze your problem and then provide a fix.

Is a Raspberry Pi fast enough?

This mainly depends on your expectations and the number of files you have. Most users report that PhotoPrism runs smoothly on a Raspberry Pi 4 with 4 GB of RAM.

Note, however, that initial indexing usually takes much longer than on a regular desktop computer and that the hardware has limited video transcoding capabilities, so video file format conversion is not well supported and software transcoding is generally slow. We take no responsibility for instability or performance problems if your device does not meet the requirements.

Should I use an SD card or a USB stick?

Due to their performance and because they can lose data over time, we do not recommend using conventional SD cards, USB sticks or external USB 2 hard disk drives to store your files, except for backups.

External Solid-State Drives (SSD) connected via USB 3 are generally reliable and fast enough to keep your originals, database, and storage folders. This way you can, for example, do the indexing on one computer, eject the drive, and then connect it to another computer to browse your pictures.

Note, though, that database files may not be binary compatible in some cases (e.g. if the version or computer architecture does not match) and could also get corrupted when you disconnect an external drive before all changes have been written to disk. We therefore recommend that you regularly create database backups, so you can easily restore your index if necessary.

View Backup Guide ›

Why don't you display animated GIFs natively?

Support for animated GIFs was added in April 2022.

Why is my storage folder so large? What is in it?

The storage folder contains sidecar, cache, and configuration files. It may also contain index database files if you are using SQLite. Most of the space there is taken up by your 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.

We are working to implement storage optimizations whenever there is an opportunity. It is also possible to increase the JPEG compression and/or limit the resolution if you are happy with lower quality thumbnails.

To free up as much space as possible, the most effective way is to delete all files in the /cache/thumbnails storage folder. It is located outside the originals folder by default, depending on your configuration. Then perform a full rescan of your library or run the command photoprism thumbs -f in a terminal if you have direct server access. This command can also be used to replace existing thumbnails, for example after changing the quality settings. Higher resolution thumbnails cannot be automatically removed at this time.

If you have a fast CPU and enough memory, you can choose to render certain thumbnails only on demand. However, storage is usually so cheap that most users opt for better quality and performance instead.

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, since videos transcoded to AVC are not as heavily compressed.

Change Settings ›

Can I skip creating thumbnails completely?

The smallest configurable size is 720px for use by the indexer to perform color detection, image classification, as well as face detection and recognition. Recreating them every time they are needed is too demanding even for the most powerful servers. Unless you have just a few small pictures, this would make the app unusable.

Reducing the Static Size Limit of thumbnails has a significant impact on face recognition and image classification results. Simply put, it means that the indexer can no longer see properly.

When should I perform a complete rescan?

We recommend performing a complete rescan after major updates to take advantage of new search filters and sorting options. Be sure to read the notes for each release 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 by navigating to Library > Index, selecting "Complete Rescan", and then clicking "Start". Manually entered information such as labels, people, titles or captions will not be modified when indexing, even if you perform a "complete rescan". Be careful not to start multiple indexing processes at the same time, as this will lead to a high server load.

How can I shorten the startup time after a restart or update?

To reduce startup time, do not set PHOTOPRISM_INIT to avoid running additional setup scripts, and set PHOTOPRISM_DISABLE_CHOWN to "true" to disable automatic permission updates.

View Config Options ›

If your instance doesn't start even after waiting for some time, our Troubleshooting Checklists help you quickly diagnose and solve the problem.

Why are files uploaded via WebDAV not indexed/imported immediately?

PHOTOPRISM_AUTO_INDEX and PHOTOPRISM_AUTO_IMPORT let you specify how long PhotoPrism should wait before indexing or importing newly uploaded files. The default setting is 300 seconds, or 5 minutes. This is a safety mechanism for users with slow uploads to avoid incomplete file sets, for example when uploading pictures with sidecar files. You can therefore reduce the delay if you have a fast connection and usually do not upload stacks of related files such as RAW images with sidecar JPEG and XMP files.

In some cases, it is also possible that the index is already being updated, so you will have to wait until the process is complete before indexing new files.

I'm having issues understanding the difference between the import and originals folders?

You may optionally mount an import folder from which files can be transferred to the originals folder in a structured way that avoids duplicates. Imported files receive a canonical filename and will be organized by year and month.

Most users with existing photo libraries will want to index their originals folder directly without importing files, leaving the existing file and folder names unchanged. On the other hand importing is an efficient way to add files, since PhotoPrism doesn't have to search your originals folder to find new files.

View First Steps 👣 ›

Can I use PhotoPrism to sort files into a configurable folder structure?

You have complete freedom in how you name your files and folders. So if you don't like the unique names and folders used by the import feature, you can instead use external tools like ExifTool, PhockUp, or Photo Organizer to reorganize your files based on their metadata.

In addition, starting with the next release, advanced users will be able to configure the import destination file path pattern through the settings.yml config file. However, this will not (yet) allow you to rename files that have already been imported, as this may cause conflicts with other tools or instances that may be accessing your files. Renaming existing files may also result in storage and/or transfer overhead with backup tools that do not recognize that files have been moved, i.e. they may create and/or transfer a new backup copy.

Thad said, we will consider adding an integrated file renaming feature once we have had time to test possible implementations for usability, performance, and security.

Learn more ›

Why is only the logo displayed when I open the app?

This may happen when the server cannot be reached, for example, because a proxy is misconfigured, JavaScript is disabled in your browser, an ad blocker is blocking requests, or you are using an incompatible browser.

We recommend going through the checklist provided and to verify that your browser meets the system requirements.

Learn more ›

Why is PhotoPrism getting stuck in a restart loop?

This happens when Docker was configured to automatically restart services after failures.

We recommend going through the checklist for fatal server errors and to verify that your computer meets the system requirements.

Learn more ›

Can I install PhotoPrism in a sub-directory on a shared domain?

Setting up PhotoPrism behind a reverse proxy in a sub-directory on a shared domain is possible in principle. This method is experimental, however, and not generally recommended because a number of detailed issues remain to be addressed and technical expertise is required.

I could not find a documentation of config parameters?

We maintain a complete list of config options in Getting Started. When you run photoprism help in a terminal, all commands and parameters available in your currently installed version are listed:

docker compose exec photoprism photoprism help

Our Docker Compose examples are continuously updated and inline documentation has been added to simplify installation.

What exactly does the read-only mode?

When read-only mode is enabled, all features that require write permission to the originals folder are disabled, e.g. WebDAV, uploading and deleting files. To do this, set PHOTOPRISM_READONLY to "true" in the environment section of your compose.yaml file. You can additionally mount volumes with the :ro flag so that writes are also blocked by Docker.

In which cases could files in the originals folder get modified?

PhotoPrism generally does not write to the originals folder, with the following exceptions: (1) You rotate an image in the user interface, so its Exif header must be updated. (2) You unstack files that were stacked based on their name, so they must be renamed. (3) You add files using the import functionality or the web upload. (4) You manually delete files in the user interface. (5) You have configured the originals folder as your sidecar folder. (6) You access the originals folder with a WebDAV client to manage your files without having read-only mode enabled.

How can I uninstall PhotoPrism?

This depends on how you installed it. If you're running PhotoPrism with Docker Compose, this command will stop and remove the Docker container:

docker compose rm -s -v

Please refer to the official Docker documentation for further details.

How can I mount network shares with Docker?

Shared folders that have already been mounted on your host under a drive letter or path can be used with Docker containers like any other directory. In addition, certain types of network storage like NFS (Unix/Linux) and CIFS (Windows/Mac) can also be mounted directly with Docker Compose.

For more information, see the Network Storage section of our Docker Troubleshooting Guide.

Learn more ›

Why does changing permissions using chmod not work for my network shares?

This is a common issue with NFS shares. For security reasons, the permissions must be changed on the server for them to take effect, unless the server allows them to be changed remotely, which depends on the settings. Even then, in the worst case, the actual permissions on the server and the effective ones on the clients may be different.

Learn more ›

Do you support Podman?

Podman works just fine both in rootless and under root. Mind the SELinux which is enabled on Red Hat compatible systems, you may hit permission error problems.

More details on how to run PhotoPrism with Podman on CentOS in this blog post, it includes all the details including root and rootless modes, user mapping and SELinux.

Learn more ›

Do you have plans to add support for LDAP or Active Directory?

PhotoPrism offers support for secure single sign-on via OpenID Connect (OIDC). With our Pro Edition, you can also configure an LDAP or Active Directory server to authenticate users.

Learn more ›

Is it possible to set a default role for new OpenID Connect users?

For security reasons, our Personal Editions currently default to the Guest role, which admins can then upgrade after checking the eligibility of newly registered1 accounts.

Learn more ›

Can I configure a custom claim as the preferred OIDC username?

You can choose between preferred_username, name, nickname and verified2 email, where preferred_username is the default. The other claims are used as fallback if no value is returned for the configured claim.

Please note that it is currently not possible to use other standard or non-standard claims, as these may not be suitable for generating a username and no logic is implemented for doing so.

Learn more ›

Who can I contact if I have a complaint about your software?

Please read this documentation and determine the cause of your problem before opening invalid, duplicate and/or incomplete bug reports, starting a public "shitstorm" or insulting other community members in our forums and chat rooms. Not only is this annoying for everyone, but it also keeps our team from working on features and improvements that our users are waiting for.

Learn more ›

Professional Users

The feature set and support options of our Community Edition are intended for personal use. Enterprise users are welcome to contact us for a commercial license and professional services.

  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 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. ↩