Frequently Asked Questions¶
General¶
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 are some features only available to members?
PhotoPrism is 100% self-funded and independent. Voluntary donations do not cover the cost of a team working full time to provide you with updates, documentation, and support. It is your decision whether you want to sign up to enjoy additional benefits.
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.
When exactly will new features be released?
Our Project Roadmap shows what tasks are in progress and what features will be implemented next. You may give ideas you like a thumbs-up, so we know what's most popular.
Be aware that we have a zero-bug policy and do our best to help users when they need support or have other questions. This comes at a price though, as we can't give exact release dates for new features. Our team receives many more requests than can be implemented, so we want to emphasize that we are in no way obligated to implement the features, enhancements, or other changes you request. We do, however, appreciate your feedback and carefully consider all requests.
Since sustained funding is key to quickly releasing new features, we encourage all users to support our mission by signing up as a member or purchasing a commercial license.
Membership¶
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.
Are there alternatives to a recurring subscription?
Yes, our Plus members automatically receive a free Lifetime Essentials membership after 24 months. Likewise, Silver members receive a Lifetime Plus membership after 24 months, Gold members after 12 months, and Platinum members after only 6 months.
If you would like to sign up for a Silver, Gold or Platinum membership, you can do so either directly on our website or on Patreon. In addition, we are working on a Plus Feature Pack that includes just the features without support, so we can offer it to you at a lower price.
Note that as a lifetime member you will always receive updates and support for your personal use from us, unlike with so-called lifetime licenses, which may only be good until the next major version is released.
What happens if I cancel my membership?
If you are eligible for a Lifetime Essentials or Plus membership, you can continue to use these features even if you decide to stop supporting us. Otherwise, you can continue to use all the freely available features. In no case will you lose access to your pictures.
User Interface¶
Can I select multiple pictures at once?
Yes, this is possible. How it works depends on what kind of device you use.
Desktop Browser
Select the first picture by clicking in the lower right corner.
The user interface is now in selection mode:
- to additionally select individual pictures, click them anywhere except on the play/view icons in the corner
- to select multiple pictures at once, use a shift+click to select all pictures between the last selected picture and the one you shift+click
Mobile Devices
Select the first picture with a long touch.
The user interface is now in selection mode:
- to additionally select individual pictures, touch them anywhere except on the play/view icons in the corner
- to select multiple pictures at once, use a long touch to select all pictures between the last selected picture and the one you long touch
Can I use trees for organizing my pictures and albums?
Except in Library > Originals and for object classification in Labels, PhotoPrism does not support hierarchically organized content for a number of reasons:
First, there are many tools (including Windows Explorer and Mac OS Finder) that already browse folders in such a way.
A common UX challenge is dealing with namespaces. For example, the album "Berlin" may exist 5 times in different parts of a tree. To avoid ambiguities, simple input fields need to be replaced with a tree browser that shows the complete context. This is especially difficult on mobile screens.
Personal albums can typically be browsed by time, with optional filters for more specific results. This is different in Enterprise asset management, where trees are required to manage responsibilities & permissions. We might do a special release for professional users later.
While you have complete freedom with organizing your original files and folders, we don't think trees should be an integral part of our user interface. Most users won't be able to sort their memories in a strictly hierarchical way and prefer to explore them in multiple dimensions instead.
Maps & Places¶
Why are some pictures positioned at unvisited locations on the map?
PhotoPrism can estimate the location of pictures taken without GPS information by extrapolating it from the location of other pictures taken on the same day. These estimates can be disabled in the settings if you don't want them.
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.
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.
Media Library¶
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 like 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.
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.
Metadata 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 description 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.
Why are my video files not indexed?
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.
Some files seem hidden, where are they?
If the quality filter is enabled, you might find them in Search > Review. Otherwise, their format may not be supported, they may be corrupted, or they may be stacked with other files if their name, exact date & location, or unique image ID indicate they belong to the same photo. You may then unstack them if this happened by mistake e.g. because of bad metadata.
For what reasons can files be stacked?
- Files that share the same file and folder name (except for the file extension) are always stacked, for example
/2018/IMG_1234.jpgand/2018/IMG_1234.avi - Files with sequential names like
/2018/IMG_1234 (2).jpgand/2018/IMG_1234 (3).jpgcan be stacked as well (optional) - File metadata indicates that the pictures were taken at the same position within the same second (optional)
- File metadata includes the same Unique Image ID or XMP Instance ID (optional)
You can change your preferences for 2 - 4 in the Stacks section under Settings > Library.
Note that it is not possible to disable stacking of files with the same name as this would break important functionality, most notably support for Apple Live Photos (which consist of a photo and a video file), any other multi-file/hybrid formats like RAW/JPEG, and indexing of metadata from XMP/JSON sidecar files.
Are files automatically unstacked when I change the settings?
When you change the stacks-related settings under Settings > Library, files that are already stacked will not be unstacked automatically. This is because unstacking is a resource-intensive operation that requires each file to be re-indexed.
The result also depends on the exact order in which you unstack the files, as non-media sidecar files, for example, remain bound to the remaining media file in a stack. We consider providing a command for this in a future release and appreciate any contributions in this regard.
If you are new to PhotoPrism and want to re-index your library with different settings, you can run the photoprism reset command in a terminal to reset the index and start from scratch.
I already indexed some files. Why are Folders, Calendar and Moments still empty?
Folders, Calendar and Moments are populated at the end of the indexing process.
Why can't I see all of my pictures in the Calendar view?
The monthly albums in this view only include pictures that have a valid creation date and time specified in their metadata or as part of their filename. Files for which the creation date is estimated based on the file modification time will therefore not appear in these albums, even if they have been properly indexed.
Why does the count in Search not match the count of files in Originals?
Library > Originals shows actual files, whereas Search counts unique photos and videos.
Photos and videos may have more than one file, for example:
- A raw file + related jpg file + related xmp file = 3 files, 1 photo
- A mp4 file + related jpg file = 2 files, 1 video
It is also possible that multiple .jpg files are stacked because they are related to each other.
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 descriptions 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.
Can I use the web interface to permanently delete files?
Yes, you can permanently delete files.
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.
RAW Images¶
What is a RAW image file?
Professional and semi-professional photographers often keep their originals in a lossless RAW format, close to how they were taken with the physical sensor, rather than in a compressed image format like JPEG, especially if they shoot with a digital SLR camera. Newer mobile phones may also be able to capture images in RAW mode. Our goal is to provide top-notch support for all RAW images, regardless of camera make and model. A full list of file types and extensions can be found in our Knowledge Base.
Since web browsers generally cannot display RAW image files directly, they must be converted. This is done during import or initial indexing. It can also be triggered manually in a terminal with the photoprism convert command.
Will JPEGs be updated when the related RAW or XMP files change?
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 description, 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.
Are edits preserved when converting a RAW image with an XMP sidecar file?
PhotoPrism currently supports Darktable and RawTherapee as RAW image converters. Darktable fully supports XMP sidecar files, RawTherapee might only partially. However, XMP is only a "container" format, so the fields (namespaces) used there to indicate how an image should be converted (as well as other metadata) differ between Lightroom/Photoshop, Darktable, and RawTherapee.
In other words, just because an application generally supports XMP that doesn't mean it can use metadata created with another application or by another vendor like Adobe. If you think that's confusing, well, that's because it is. You have an open format, but you still suffer from vendor lock-in - probably not entirely unintentional on Adobe's part.
From our experience, some basic edits done with Adobe tools - such as cropping - might be preserved when you convert the same RAW image with other software like Darktable. Advanced edits, such as lens or color corrections, will likely not be applied.
Live Photos¶
Why can't I play Live Photos or find stacks when I search for specific images?
Our search API and user interface perform a file search. This is intentional since "stacks" can contain files of different types and properties, such as color.
For example, there may be color and monochrome versions. Now, when you search for them or sort them by color, the user interface must display individual files. Otherwise, the results showing a color image/video when you filter by monochrome would make no sense.
Likewise, if you search for filename.mp4.*, you will find only JPEGs without video, because the video file extension is .mp4 without an extra dot at the end.
We recommend using the path: and/or name: filters with wildcards if searching for individual files limits the search results too much. Most users will want to find all related files so that they can be displayed together, e.g. as live photos consisting of a video and an image.
You can combine these filters with other filters such as live to ensure that the results include only pictures with a specific media type. Alternatively, you can use the filename: filter with a more permissive wildcard that excludes the file extension.
Metadata¶
Windows shows different metadata values. Could this be a bug in PhotoPrism?
We recommend that you use ExifTool to see all metadata fields and values, as Windows has limited functionality.
It might then become clear why there are differences. For example, it could be that Windows does not support some fields and therefore ignores them, or that the data shown is actually from the file system and not from the files. Should you still believe to have found a bug, please provide us with sample files so that we can reproduce the issue.
Why is the date of pictures without metadata displayed as Unknown in the search results?
If there is no date information available in the metadata or the original file names, the file system modification time is used to sort pictures in search results and to create canonical file names for them during import. However, this is usually not the actual date a photo was taken (or a graphic was created by the original author), but only the time you downloaded or copied it. As a result, the date of pictures without a reliable creation date will be displayed as "Unknown" until you manually set a date in the edit dialog.
Why do some pictures have 08/12/2002 as date if they were not taken on that day?
This is usually caused by a bug in Android that caused photos to be created with an incorrect CreateDate. While the date can easily be changed in the edit dialog, this only updates the index without modifying your originals. To fix the date directly in your image or video files, please use other applications like Photoshop, or ExifTool, and re-index your library.
Why do some pictures have an odd date like 01/01/1980?
This may happen in case there was an issue with your camera's settings when the photo was taken. While the date can easily be changed in the edit dialog, this only updates the index without modifying your originals.
To fix the date directly in your image or video files, please use other applications like Photoshop, or ExifTool, and re-index your library.
What's the difference between keywords and labels?
Keywords contain a list of search terms extracted from metadata, file names, and other sources like geodata. Pictures with matching keywords automatically show up in related Labels.
Although related, keywords and labels serve different purposes:
-
Labels may have parent categories and are primarily used for classification, like "animal", "cat", or "boat". Duplicates and ambiguities should be avoided.
-
Keywords are primarily used for searching. They may include similar terms and translations, like "kitten", "kitty", and "cat".
How can I check the metadata of images and videos?
We recommend using Exiftool if some of your pictures are displayed incorrectly (stretched, distorted), information seems to be missing (e.g. title or description), or the wrong time and location are shown.
Thumbnails¶
Isn't it insecure that thumbnail image URLs work even if you are not logged in?
Like most commercial image hosting services, we've chosen to use a cookie-free thumbnail API to minimize request latency and avoid unnecessary network traffic. If you were to copy private session cookies and use them in a different browser window, you would have a similar problem, except that they also work for other API endpoints, not just a single image.
Even if URLs were to become invalid every minute: Digital copies are as good as originals. Once shared and downloaded, such images should be considered "leaked" because they are cached and can be re-shared by the recipient at any time, with no sure way to get all copies back. Any form of protection we could provide would essentially be "snake oil", could be circumvented, and would have a negative impact on the user experience, such as disabling the browser cache or context menu.
For the highest level of protection, it is recommended to shield your private server from the public Internet. Always use HTTPS, a VPN and/or ideally TLS client certificates and make sure that only people you trust have access to your instance.
Visit docs.photoprism.app/developer-guide/media/thumbnails/ to learn more.
WebDAV¶
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.
Why do I get an error when trying to add a remote server for syncing?
When adding a new remote server, PhotoPrism tests a number of common endpoints. Only when that fails, you'll see an error. There may be different reasons for this:
- you are using HTTPS with an invalid certificate (not signed, outdated, domain doesn't match,...)
- your server has permission issues, or an otherwise bad configuration. For example, Nextcloud blocks requests
if the host doesn't match
trusted_domainsin itsconfig.php - the IP is not reachable from your PhotoPrism instance due to network settings, or a firewall
- the internal hostname can not be resolved to an IP address
- it's the wrong host or port
- username or password are wrong
Curl is an excellent tool for testing HTTP connections if you don't mind using a terminal:
curl -X PROPFIND -H "Depth: 1" -u user:pass https://example.org/webdav/
To avoid overlooking issues, it's best to run it from the same Docker container, virtual machine, or server environment where PhotoPrism is installed.
My file sync app fails with "unable to parse TLS packet headers" when trying to connect via WebDAV?
Because of security considerations, some backup tools and file sync apps like FolderSync removed support for non-SSL HTTP communication.
If you install PhotoPrism on a public server outside your home network, always run it behind a secure HTTPS reverse proxy. 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 sync apps may refuse to connect as well.