Computer Vision Commands¶
Save Model Configuration¶
To write the model configuration to a vision.yml file you can run:
docker compose exec photoprism photoprism vision save
You can then configure the vision.yml file according to your specific needs.
View Model Configuration¶
You can use the following terminal command, to inspect your current model configuration:
docker compose exec photoprism photoprism vision ls
Command Options¶
You can combine it with these flags to change the output format:
| Command Flag | Description |
|---|---|
--md, -m |
format as machine-readable Markdown |
--csv, -c |
export as semicolon separated values |
--tsv, -t |
export as tab separated values |
Run Vision Models¶
Once you have configured your preferred computer vision models and services in the vision.yml file, you can use the following command to run a model on a set of pictures, as specified by the search filter:
photoprism vision run [options] [filter]
Command Options¶
| Command Flag | Description |
|---|---|
--models MODELS, -m MODELS |
computer vision MODELS to run, e.g. caption, labels, or nsfw (default: "caption") |
--count value, -c value |
maximum number of pictures to be processed (default: 100000) |
--source TYPE, -s TYPE |
custom data source TYPE, e.g. estimate, image, meta, or manual (default: "image") |
--force, -f |
force existing data to be updated if the source priority is equal to or higher than the current one (default: false) |
To generate captions for all photos in your library, you can run:
docker compose exec photoprism photoprism vision run --models=caption
Note: Processing time will vary based on your library size and hardware performance and may take a considerable amount of time for large collections.
If you have a model for labels configured in your vision.yml you can run the following to generate labels:
docker compose exec photoprism photoprism vision run --models=labels
To generate captions only for photos matching a specific search filter such as those in a particular album, use the following command:
docker compose exec photoprism photoprism vision run --models=caption album:Holidays
To re-generate captions for photos that already have some, add the --force flag to your command:
docker compose exec photoprism photoprism vision run --models=caption --force
This is especially useful when testing different models or prompts. Note that the configured source must have a equal or higher priority than the source of the existing captions for them to be replaced.
Reset Vision Data¶
The photoprism vision reset command allows you to reset data generated by computer vision models for pictures that match the specified search filters. This is useful when you want to clear existing AI-generated data and start fresh, or when switching between different models.
photoprism vision reset [options] [filter]
Command Options¶
| Command Flag | Description |
|---|---|
--models MODELS, -m MODELS |
computer vision MODELS to reset, e.g. caption or labels |
--count NUMBER, -n NUMBER |
maximum NUMBER of pictures to be processed (default: 100000) |
--source TYPE, -s TYPE |
custom data source TYPE (auto, default, image, marker, ollama, openai, vision) (default: "image") |
--yes, -y |
runs the command non-interactively (default: false) |
You must always specify the --source flag to reset data from a specific source. Without it, the command may not reset any pictures. Use the source that matches where your data came from (e.g., ollama or image).
Examples¶
To reset captions generated by Ollama for all photos in your library:
docker compose exec photoprism photoprism vision reset --models=caption --source=ollama --yes
To reset labels for photos in a specific album:
docker compose exec photoprism photoprism vision reset --models=labels --source=ollama album:TestAlbum
The --yes flag runs the command non-interactively without requiring confirmation. Omit this flag if you want to be prompted before the reset operation begins.
Face Detection Commands¶
PhotoPrism provides specialized commands for managing face detection, clustering, and optimization. These commands are particularly useful when switching between detection engines or troubleshooting face recognition issues.
Index Faces¶
Detect faces in your photos:
docker compose exec photoprism photoprism faces index [subfolder]
Audit Face Data¶
Check the integrity of face embeddings and cluster statistics:
docker compose exec photoprism photoprism faces audit
To automatically fix normalization issues and update face distances:
docker compose exec photoprism photoprism faces audit --fix
To audit a specific person:
docker compose exec photoprism photoprism faces audit --subject=<person-uid>
This provides detailed information including:
- Retry counts for cluster merging
- Sample statistics
- Outstanding clusters that need attention
Optimize Face Clusters¶
Run the clustering optimization algorithm to merge similar face clusters:
docker compose exec photoprism photoprism faces optimize
If you've manually cleaned up problematic clusters and want to retry merging:
docker compose exec photoprism photoprism faces optimize --retry
This clears retry counters and allows the optimizer to reprocess clusters that previously failed to merge.
Reset Face Detection¶
Clear all face data and start fresh:
docker compose exec photoprism photoprism faces reset
The faces reset command will delete all existing face markers and clusters. Make sure you have backups if needed, as this operation cannot be undone.