Skip to content

NSFW Detection

PhotoPrism can automatically flag pictures as private when an image-classification model considers them unsafe for work. It can also reject such files during web upload so they never enter the library. Flagging during indexing is opt-in. Upload screening runs unless PHOTOPRISM_UPLOAD_NSFW is true, which our example compose.yaml sets. Both are intended mainly to help administrators of shared instances keep adult content out of their libraries without having to review every upload manually.

Configuration Options

Three config options govern the runtime behavior:

Config Option Default Effect
PHOTOPRISM_NSFW_MODEL auto Chooses how NSFW content is detected: auto uses the dedicated detector, labels uses the NSFW fields returned by an Ollama or OpenAI labels model, and none turns NSFW detection off.
PHOTOPRISM_DETECT_NSFW false When true, photos detected as NSFW during indexing or a photoprism vision run are marked as private. When false, NSFW signals are ignored even if the underlying model returns them.
PHOTOPRISM_UPLOAD_NSFW false When false, the web upload dialog rejects files that the dedicated detector flags as unsafe (the rejected files are deleted before indexing). When true, uploads are accepted regardless; our example compose.yaml sets it to true.

Flagging and upload screening are independent: you can reject uploads without flagging existing imports, flag existing imports without policing uploads, or both.

Which Model Detects NSFW?

In the default auto mode, PhotoPrism uses a dedicated detector that runs locally on ONNX and ships with every PhotoPrism image: Yahoo OpenNSFW. It is small and fast, and it decides with a threshold calibrated for this model. The detector does not distinguish drawings from photographs.

Other registered detectors can be downloaded in a terminal and selected in vision.yml:

docker compose exec photoprism download-models.sh falconsai_nsfw_image_detection_224
Models:
  - Type: nsfw
    Name: falconsai_nsfw_image_detection_224

The registered detectors are yahoo_open_nsfw (default), adamcodd_vit_base_nsfw_int8, adamcodd_vit_base_nsfw_fp32, falconsai_nsfw_image_detection_224, and freepik_nsfw_image_detector. Restart PhotoPrism after downloading a model or changing vision.yml. If the selected model is not installed, PhotoPrism logs a warning with the command that downloads it. If you have set a custom models path, see Label Models for how to download into it.

A Type: nsfw entry cannot use Ollama or OpenAI, as these engines do not return NSFW scores for it. PhotoPrism uses the built-in detector instead and logs a warning. To use an LLM for NSFW detection, use a labels model as described below.

Using a Labels Model

When Type: labels is served by Ollama or the OpenAI API, PhotoPrism can ask the model to include NSFW classification in the same response, avoiding a second inference pass. To use it, set both:

In this mode, the dedicated detector is not loaded, so uploads are not screened, and pictures are only flagged if the labels model returns the NSFW fields. If the labels are generated by the built-in classifier, no NSFW detection takes place.

If you switched to an Ollama or OpenAI labels model and want it to flag NSFW content, set PHOTOPRISM_NSFW_MODEL=labels as well as PHOTOPRISM_DETECT_NSFW=true. In the default auto mode, the dedicated detector decides and the labels model is not asked for NSFW fields.

NSFW Thresholds

The Thresholds block in vision.yml controls how confident a model must be before a picture is flagged. Values are whole percentages from 1 to 100; lower values are more aggressive (more pictures flagged), higher values more permissive.

Thresholds:
  NSFWUpload: -1
  NSFWIndex: -1
  NSFW: 75
Key Applies To Default
NSFWUpload The dedicated detector when screening web uploads The calibrated threshold of the detector
NSFWIndex The dedicated detector during indexing and vision run The calibrated threshold of the detector
NSFW NSFW fields returned by a labels model (labels mode only) 75

Leave NSFWUpload and NSFWIndex unset, or set them to 0 or -1, to use the threshold calibrated for the selected detector. Setting a stricter value for uploads than for indexing lets you screen uploads more aggressively without flagging more of your existing library. NSFW does not affect the dedicated detector.

Running NSFW Detection Manually

To re-evaluate the existing library after enabling or tuning NSFW detection, run the vision worker with the nsfw model in a terminal:

docker compose exec photoprism photoprism vision run --models nsfw

Add --force to override existing private flags, and restrict the run to a subset of the library by appending a search filter (same syntax as the --vision-filter config option), for example:

docker compose exec photoprism photoprism vision run --models nsfw --force public:true

Learn more ›