Skip to content

Frequently Asked Questions

What are sidecar files and where do I find them?

A sidecar is a file which sits alongside your main photo or video files, typically using the same name, and a different extension like

  • IMG_0101.jpg
  • IMG_0101.json
  • IMG_0101.yaml

New sidecar files will be created in the storage folder by default so that the originals folder can be mounted read-only.


PhotoPrism will always look out for existing sidecar files and use them for indexing, even if PHOTOPRISM_DISABLE_EXIFTOOL and PHOTOPRISM_DISABLE_BACKUPS are set to "true".

Three types of metadata sidecar files are supported currently:


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

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


PhotoPrism can also read JSON files exported by Google Photos. Support for additional schemas may be added over time.


If not disabled via PHOTOPRISM_DISABLE_BACKUPS or --disable-backups, PhotoPrism will automatically create / update YAML sidecar files while indexing and after manually editing fields like title, date, or location. They serve as a backup in case the database (index) gets lost, or when folders are synced with a remote PhotoPrism instance.

Like JSON, YAML files can be opened using common development tools and text editors. Changes won't be synced back to the original index though as this might overwrite existing data.


XMP (Extensible Metadata Platform) is an XML-based metadata container format invented by Adobe. It offers much more fields (as part of embedded models like Dublin Core) than Exif. That also makes it difficult - if not impossible - to provide complete support. Reading Title, Copyright, Artist, and Description from XMP sidecar files is implemented as a proof-of-concept, contributions welcome. Indexing embedded XMP is only possible via Exiftool, see above.

Which folder will be indexed?

This depends on your runtime 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 try to find a photo library by going through a list of common folder names like /photoprism/originals, Pictures, and ~/Photos. It will also search for other resources like external applications, classification models, and frontend assets.

Your library will be mounted from ~/Pictures by default when using our example docker-compose.yml file, where ~ is a placeholder for your home directory.

You may mount any folder accessible from your computer, including network drives. Note that PhotoPrism won't be able to see folders that have not been mounted unless you install it locally without Docker (developers only).

Multiple folders can be indexed by mounting them as sub-folders of /photoprism/originals:

  - "~/Family:/photoprism/originals/Family"
  - "~/Friends:/photoprism/originals/Friends"

Which file types are supported?

PhotoPrism's primary image file format is JPEG. While indexing, a JPEG sidecar file may automatically be created for RAW, HEIF, TIFF, PNG, BMP, and GIF files. It is required for classification and resampling.

Support for specific RAW formats depends on the runtime environment and configuration. PhotoPrism may use Darktable and RawTherapee for RAW to JPEG conversion. On Mac OS, Sips can be used as well.

We support all common video types. You should configure PhotoPrism to automatically create JSON sidecar files so that video metadata like location and duration can be indexed.

You're welcome to open an issue if you experience issues with a specific file format.

Why don't you display animated GIFs natively?

PhotoPrism focuses on photographic images and short videos. You may convert your GIF files to H.264 / MPEG-4 AVC using ffmpeg. That's also what Twitter does when you post a GIF. They will then be shown as "live photos" and start playing on mouse over while also consuming less storage and bandwidth compared to your original GIF files.

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

The storage folder contains sidecar, thumbnail, and configuration files. It may also contain index database files if you're using SQLite. Most space is consumed by thumbnails: These are high-quality resampled, smaller versions of your originals.

Thumbnails are required because Web browsers do a pretty bad job at resampling large images so that they fit your screen. Using originals for slideshows and search result previews would consume much more browser memory, and reduce overall performance, as well.

If you're happy with lower quality thumbnails, you can reduce their JPEG quality and/or set a size limit. Note that existing thumbnail files won't be replaced automatically after changing config values.

You may also choose to render thumbnails on-demand if you have a fast CPU and enough memory. However, storage is typically affordable enough for most users to go for better quality and performance instead.

Can I skip creating thumbnails completely?

The smallest configurable size is 720px for consumption by the indexer to perform color detection, face detection, and image classification. Recreating them every time they are needed is too demanding for even the most powerful servers. Unless you only have a few small images, it would render the app unusable.

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

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.

Should I use SQLite, MariaDB, or MySQL?

If you 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. The way MariaDB and MySQL handle multiple queries is completely different and optimized for high concurrency. SQLite, for example, locks the index on updates so that other operations have to wait. In the worst case, this can lead to timeout errors. Its main advantage is that you don't need to run a separate database server. This can be very useful for testing and also works great if you only have a few thousand files to index.

MariaDB lacks some features that MySQL Enterprise Edition offers. On the other hand, MariaDB has many optimizations. It is also completely open-source.

Why is PhotoPrism getting stuck in a restart loop?

This happens when Docker was configured to automatically restart the app after failures. Fatal errors are often caused by one of the following conditions:

  1. Your (virtual) server disk is full
  2. There is disk space left, but the inode limit has been reached
  3. The storage folder is not writable or there are other filesystem permission issues
  4. You have accidentally mounted the wrong folders
  5. The server is low on memory
  6. The database server is not available, incompatible or incorrectly configured
  7. There are network problems caused by a proxy, firewall or unstable connection
  8. Kernel security modules such as AppArmor and SELinux may be blocking permissions

Please search your operating system and server logs for messages like disk full, wrong permissions, and database connection failed before reporting a bug. If you are using Docker Compose, run this command to display the last 100 log messages:

docker-compose logs --tail=100

Linux kernel security can be disabled on private servers, especially if you do not have experience with the configuration. Use a file manager, or the commands chmod and chown on Unix-like operating systems, to verify and fix filesystem permissions. Available disk space can be displayed with df -h. The size of virtual disks and memory can be increased in Docker and VM settings if needed. Please refer to the documentation.

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

This is possible with our latest release if you run it behind a proxy. Note that for a Progressive Web App (PWA) to work as designed, the service worker should be located in the root directory. Also keep in mind sharing a domain with other apps may negatively impact the performance and security of all apps installed. The length of share links increases as well.

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 you enable read-only mode, all features that require write permission to the originals folder are disabled, in particular import, upload, and delete. Set PHOTOPRISM_READONLY to "true" in docker-compose.yml for this. You can mount a folder with the :ro flag to make Docker block write operations as well.

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?

There are multiple ways of using network storage. One of the easiest might be to directly mount NFS shares with Docker.

You can mount any number of NFS shares as folders. Follow this docker-compose.yml example if you want to mount the originals folder as a share:

    # ...
      # Map originals folder to NFS:
      - "photoprism-originals:/photoprism/originals"     

    driver: local
      type: nfs
      # The IP of your NAS:
      o: "username=user,password=secret,addr=,soft,rw"
      # Share path on your NAS:
      device: ":/mnt/photos" 

For Windows / CIFS shares:

    driver: local
      type: cifs
      o: "username=user,password=secret,rw"
      device: "//host/folder"


This was tested with TrueNAS and NFS, but other (network) file systems may be mounted with Docker as well.


Mounting the import folder to a share which is also accessible via other ways (e.g. CIFS) is especially handy, as you can dump all data from a SD card / camera directly into that folder and trigger the index in the GUI afterwards. So you can skip the upload dialog in the GUI and it's a little faster.

I'm using an operating system without Docker support. How to install and use PhotoPrism without Docker?

In general, you would build / install it like a developer since we don't have packages for specific operating systems yet.

Instead of using Docker, you can manually type the commands listed in our development Dockerfile and replace packages with what is available in your environment. You often don't need to use the exact same versions for dependencies.

If your operating system has Docker support, we recommend learning Docker as it vastly simplifies installing and upgrading.

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

Do you provide LXC images?

There is currently no LXC build for PhotoPrism, see issue #147 for details.

Any plans to add support for Active Directory, LDAP or other centralized account management options?

There is no single sign-on support yet as we didn't consider it essential for our initial release. Our team is currently working on OpenID Connect, which will be available in a future release.


Our development and testing efforts are focused on small servers and home users. Adding functionality that is primarily useful for business environments, or that only benefits few private users with special needs, diverts resources away from features that benefit everyone. Professional users are welcome to reach out to us for a custom solution.