If your server has an NVIDIA graphics card, PhotoPrism® Pro can use it to run its built-in AI models for image classification, NSFW detection, and face recognition. This makes indexing faster, while image decoding and thumbnail generation still run on the CPU.

Requirements

  • a server with a 64-bit Intel or AMD processor, as the GPU image is not available for ARM
  • an NVIDIA graphics card with the proprietary NVIDIA driver installed on the server
  • the NVIDIA Container Toolkit, so that Docker can pass the graphics card to a container
  • PhotoPrism® Pro installed with Docker Compose, as described in our Quickstart Guide, or on Kubernetes

To check that the driver works, run nvidia-smi on the server. It should list your graphics card.

Setup

Step 1: Change the Image

Our photoprism/pro:cuda image includes everything PhotoPrism® Pro needs to use an NVIDIA GPU. Open your compose.yaml file, replace photoprism/pro:latest with photoprism/pro:cuda, and add a deploy section that assigns the graphics card to the photoprism service:

services:
  photoprism:
    image: photoprism/pro:cuda
    deploy:
      resources:
        reservations:
          devices:
            - driver: "nvidia"
              capabilities: [gpu]
              count: 1

All other settings, such as your storage volumes and config options, stay the same. Make sure the deploy section has the same indentation as image.

Step 2: Restart PhotoPrism® Pro

Open a terminal, change to the folder where your compose.yaml file is located, and run these commands to download the image and restart the service:

docker compose pull
docker compose up -d

The cuda image is about 1.7 GB larger than our regular image, so the download may take a little longer. It is updated together with the regular image, so updating works in the same way. If you want to stay on a specific release, you can use a version tag such as photoprism/pro:1.2610.07-cuda instead.

Do not add onnxruntime or onnxruntime-gpu to PHOTOPRISM_INIT when using the cuda image, as it already includes the required libraries. The image also sets PHOTOPRISM_ONNX_PROVIDER to cuda, so no further configuration is needed.

Kubernetes

When you deploy PhotoPrism® Pro with our Helm chart version 1.1.6 or later, set the image tag to cuda and request a GPU in your values file. This requires the NVIDIA GPU Operator or the NVIDIA device plugin in your cluster:

image:
  tag: "cuda"
resources:
  limits:
    nvidia.com/gpu: 1

If the NVIDIA container runtime is not the default runtime of your cluster, also set runtimeClassName: "nvidia". You can use nodeSelector, tolerations, and affinity to schedule the pod on a node with a GPU.

To check the logs as described below, use kubectl logs with the name of the PhotoPrism® Pro pod instead of docker compose logs photoprism.

Checking That the GPU Is Used

When PhotoPrism® Pro loads a model, it logs a line that names where the model runs. The models are loaded when they are first needed, so start indexing in the user interface and then show these lines with the following command:

docker compose logs photoprism | grep -E "on the cuda|execution provider"

If the GPU is used, the output includes lines like these:

faces: loading yunet on the cuda
classify: loading efficientformerv2_s2 on the cuda with ONNX Runtime from libonnxruntime.so
nsfw: loading yahoo_open_nsfw on the cuda with ONNX Runtime

While pictures are being indexed, nvidia-smi on the server also lists a photoprism process with the GPU memory it uses.

If the GPU cannot be used, PhotoPrism® Pro logs one warning that the “cuda execution provider is unavailable” and runs the models on the CPU instead, so indexing still works. Common causes are a missing deploy section, a driver that is not installed or too old, and a missing NVIDIA Container Toolkit. PhotoPrism® Pro does not switch to the GPU later on its own, so restart it with docker compose restart photoprism after you have fixed the cause.

Hardware Video Transcoding

The cuda image can also use the graphics card to transcode videos with NVIDIA NVENC. To enable this, add the following to the environment section of the photoprism service and restart it:

      PHOTOPRISM_FFMPEG_ENCODER: "nvidia"

What to Expect

How much faster indexing gets depends on your graphics card and your CPU. With an NVIDIA GeForce RTX 4060, indexing a library of about 2,400 photos and 280 videos was 1.8 times faster than with an Intel Core i7-14700 alone, with identical results. An entry-level card such as an NVIDIA T400 ran the AI models no faster than a recent CPU, because decoding the images on the CPU takes most of the time.

During indexing, PhotoPrism® Pro used up to about 6 GB of GPU memory on the RTX 4060. If you also run Ollama on the same card, it may not have enough memory left for its model, so consider reducing the number of index workers with PHOTOPRISM_INDEX_WORKERS.

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: