Documentation
Everything you need to get started with Vireo.
Getting Started
1. Install Vireo
Download the installer for your platform from the download page and run it. On macOS, drag Vireo to your Applications folder. On Windows, run the setup wizard. On Linux, install the .deb package.
2. Add your photo folders
Open Vireo and click Add Folder in the sidebar. Navigate to any directory containing your wildlife photos. Vireo reads your files in place — nothing is moved or copied. You can add multiple folders.
3. Run your first scan
Click Scan to start the classification pipeline. Vireo will detect subjects, classify species, and score quality for every photo. Progress streams in real time — you can watch the log panel for details. First runs download models (~500 MB), so give it a few minutes.
4. Review results
Once the scan completes, every photo has a label: keep, review, or reject. Open the Cull page to rapidly sort through them. Use keyboard shortcuts to move through photos and make decisions.
5. Sync to XMP
When you're happy with your decisions, sync changes to XMP sidecars. This writes standard metadata that Lightroom, Darktable, and other tools can read. Your decisions travel with your files.
FAQ
How do I add photos to Vireo?
Getting StartedOpen Settings and add a folder under Scan Roots. Then go to the Jobs page and click Scan. Vireo will find all supported image files in that folder and its subfolders. First runs download AI models (~500 MB), so give it a few minutes.
How do I classify my photos?
Getting StartedRun a scan from the Jobs page. The classification pipeline detects subjects, identifies species, and scores quality for every photo. Progress streams in real time in the log panel.
How do I review scan results?
Getting StartedAfter a scan completes, every photo gets a label: keep, review, or reject. Open the Cull page to rapidly sort through them using keyboard shortcuts.
How do I save my decisions to my photo files?
Getting StartedUse the Sync feature to write changes to XMP sidecar files. This writes standard metadata that Lightroom, Darktable, and other tools can read. Your original image files are never modified.
Where are my photos stored?
PhotosOn your filesystem, exactly where you put them. Vireo reads photos in place and never moves, copies, or uploads them. The database is just a cache — you can rebuild it anytime from your files.
Does Vireo modify my original photo files?
PhotosNo. Metadata is written to XMP sidecar files (.xmp) alongside your photos. Your original image files are never touched.
How do I delete or remove a photo?
PhotosIn Browse view, select a photo and use the reject action. This marks the photo for rejection but does not delete the file from disk. Vireo never deletes your files.
How do I move photos to a different folder?
PhotosUse the Move page to relocate photos to a different folder. Select photos and choose a destination. Vireo moves the actual files on disk and updates its database.
What is the Pipeline page?
ClassificationThe Pipeline page shows you exactly how Vireo processes each photo: subject detection, species classification, and quality scoring. You can see bounding boxes, confidence scores, and quality metrics for any photo.
What species can Vireo identify?
ClassificationOver 10,000 species, depending on the model. The iNaturalist-trained classifier covers the broadest range. You can run multiple models and compare predictions.
How does culling work?
CullingThe Cull page groups similar photos and lets you quickly decide which to keep. Vireo scores photos on focus, exposure, composition, and noise to suggest the best shots. Use keyboard shortcuts to move through photos rapidly.
How do I add keywords to photos?
KeywordsOpen the Keywords page to manage your keyword hierarchy. You can add keywords to individual photos or in bulk. Keywords are global — they're shared across all workspaces.
Can I import keywords from Lightroom?
KeywordsYes. Vireo can import keyword hierarchies from Lightroom catalog files (.lrcat). Your XMP sidecars are also compatible with Lightroom, so you can use both tools on the same library.
What are collections?
CollectionsCollections let you group photos together regardless of which folder they're in. Collections are workspace-scoped, so each workspace has its own set.
What are workspaces?
WorkspacesWorkspaces let you organize your work into separate contexts. Each workspace has its own predictions, collections, and pending changes. Photos and keywords are shared across all workspaces. A Default workspace is created automatically.
How do I create a new workspace?
WorkspacesGo to the Workspace page and click the button to create a new workspace. Give it a name and it's ready to use. You can switch between workspaces from the workspace switcher.
Do I need an internet connection?
SettingsOnly for downloading AI models on first use. After that, everything runs locally on your machine. No cloud processing, no uploads, no accounts.
Do I need a GPU?
SettingsNo, but it helps. Classification runs on CPU if no GPU is available — it's just slower. A CUDA-compatible NVIDIA GPU will significantly speed up large scans.
How do I use Vireo with Darktable?
SettingsConfigure the Darktable binary path in Settings. You can then send photos to Darktable for editing, apply styles, and export processed versions. If you shoot Nikon High Efficiency NEFs, enable auto-convert to DNG and configure Adobe DNG Converter if Vireo cannot auto-detect it.
Is Vireo free?
SettingsYes. Vireo is free and open source under the MIT license. You can use it, modify it, and contribute to it.
Looking for more?
For technical documentation, troubleshooting, API details, and contributing guidelines, visit the project on GitHub.
View on GitHub