Thumbnail Generation and Storage¶
Introduction¶
PhotoPrism uses libvips (via the govips bindings) to generate thumbnails for display in search results and in the full-screen viewer. The previous native disintegration/imaging fallback was removed in the April 2026 release — libvips is now the only image-processing library; the PHOTOPRISM_THUMB_LIBRARY option is preserved for backwards compatibility but has no effect.
The smallest configurable size limit is 720px, which corresponds to the fit_720 thumbnail size. Most sizes up to 720x720 will be generated by default and should therefore always be available.
Besides their obvious use in the frontend, the indexer also uses thumbnails for color detection, face recognition and image classification, see Advanced Settings in the User Guide.
Standard Sizes¶
The smallest configurable static and dynamic size limit is 720px, so most sizes up to fit_720 are always generated by default.
Higher size limits generate thumbnails with more detail at higher resolutions - either statically (pre-generated while indexing) or on demand if the configuration permits.
Optional thumbnail sizes cannot be pre-generated and are only rendered on request, for example when sharing an image on Instagram.
The following overview shows the name, dimensions, and aspect ratio for each thumbnail size as well as a description of how it is used:
| Name | Width | Height | Aspect Ratio | Available | Usage |
|---|---|---|---|---|---|
| colors | 3 | 3 | 1:1 | Always | Color Detection |
| tile_50 | 50 | 50 | 1:1 | Always | List View |
| tile_100 | 100 | 100 | 1:1 | Always | Places View |
| left_224 | 224 | 224 | 1:1 | On-Demand | AI |
| right_224 | 224 | 224 | 1:1 | On-Demand | AI |
| tile_224 | 224 | 224 | 1:1 | Always | AI, Mosaic View |
| left_384 | 384 | 384 | 1:1 | Optional | AI |
| right_384 | 384 | 384 | 1:1 | Optional | AI |
| tile_384 | 384 | 384 | 1:1 | Optional | AI |
| left_480 | 480 | 480 | 1:1 | Optional | AI |
| right_480 | 480 | 480 | 1:1 | Optional | AI |
| tile_480 | 480 | 480 | 1:1 | Optional | AI |
| tile_500 | 500 | 500 | 1:1 | Always | Cards View |
| fit_720 | 720 | 720 | Preserved | Always | SD TV, Mobile |
| tile_1080 | 1080 | 1080 | 1:1 | Optional | |
| fit_1280 | 1280 | 1024 | Preserved | On-Demand | HD TV, SXGA |
| fit_1600 | 1600 | 900 | Preserved | Optional | Social Media |
| fit_1920 | 1920 | 1200 | Preserved | On-Demand | Full HD |
| fit_2048 | 2048 | 2048 | Preserved | Optional | DCI 2K, Tablets |
| fit_2560 | 2560 | 1600 | Preserved | On-Demand | Quad HD |
| fit_3840 | 3840 | 2400 | Preserved | Optional | 4K Ultra HD |
| fit_4096 | 4096 | 4096 | Preserved | On-Demand | DCI 4K, Retina 4K |
| fit_5120 | 5120 | 5120 | Preserved | On-Demand | Retina 5K |
| fit_7680 | 7680 | 4320 | Preserved | On-Demand | 8K Ultra HD 2 |
Color Profiles¶
sRGB is the standard color space used when generating thumbnails. An ICC color profile for wide-gamut displays can optionally be embedded.
File Storage¶
Generated thumbnail files are stored in the storage/cache/thumbnails folder, where the path and file name depend on the thumbnail size and original file hash, e.g.:
storage/cache/thumbnails/1/a/3/1a30c1f...9_100x100_center.jpg
Downscaling Filters¶
libvips uses a Lanczos 3-lobe kernel for all resizing operations; the PHOTOPRISM_THUMB_FILTER option is retained for backwards compatibility but has no effect with the current library (internal/thumb/filter.go:ParseFilter returns ResampleAuto for every input when lib == LibVips). The notes below describe the algorithms used in earlier releases and remain useful as background reading.
Linear¶
Bilinear interpolation takes a weighted average of the four neighborhood pixels to calculate its final interpolated value. The result is a much smoother image than the original; when all known pixel distances are equal, the interpolated value is simply their sum divided by four. Bilinear interpolates in both directions (horizontal and vertical) and gives a better result than nearest-neighbor interpolation at less computational cost than bicubic.
Cubic¶
Catmull-Rom is a local interpolating spline developed for computer graphics. Catmull-Rom splines are a family of cubic interpolating splines in which the tangent at each point is calculated from the previous and next point on the spline. The results are similar in sharpness to bicubic interpolation, but the Catmull-Rom reconstruction is clearly superior in smooth signal regions.
Lanczos¶
Lanczos interpolation smoothly interpolates pixel values by mapping each sample of the given image to a translated and scaled copy of the Lanczos kernel — a sinc function windowed by the central hump of a dilated sinc function. The sum of these translated and scaled kernels is then evaluated at the desired pixel. Lanczos has the best properties in terms of detail preservation and minimal aliasing artifacts for geometric transformations not involving strong downsampling. Higher-order Lanczos interpolation requires more compute, which is why fixed 3-lobe Lanczos is the practical default.
Blackman¶
Blackman is a modification of Lanczos with better control of ringing artifacts.
Server API¶
Like most commercial image hosting services, we have chosen to implement a cookie-free thumbnail API to minimize request latency by avoiding unnecessary network traffic.