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 11, run the public-beta setup wizard. On Linux, install the .deb package.
2. Import your photos
Open Import, leave Add in place selected, and click Browse to choose one or more folders. Vireo indexes the photos where they already live — nothing is moved or copied. Choose Copy to archive instead only when you want Vireo to copy photos from a card or source folder into your archive.
3. Choose what happens after import
Under After import, choose a processing option such as Identify birds, then click Start import. Vireo adds the photos to the active workspace and starts processing as a background job. First runs may download AI models — anywhere from a few hundred megabytes to a few gigabytes — so give them a few minutes. Use Jobs only to monitor progress.
4. Review results
Open Process Review to inspect classifications and any available quality recommendations. When culling analysis is available, open Cull to rapidly mark photos keep, review, or reject with keyboard shortcuts. Use Process later when you want to rerun processing for photos already in the workspace.
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 Import, leave Add in place selected, and click Browse to choose one or more folders. Select an After import processing option, then click Start import. Vireo adds supported photos and their subfolders to the active workspace without moving or copying them. Choose Copy to archive instead when you want Vireo to copy photos into your archive.
How do I classify my photos?
Getting StartedWhen adding photos, choose a processing option under After import before clicking Start import. For photos already in the workspace, open Process, select the workspace folders, choose a strategy, and click Start Pipeline. Jobs shows progress; it is not where processing starts.
How do I review processing results?
Getting StartedOpen Process Review to inspect classifications and any available quality recommendations. When culling analysis is available, open Cull to rapidly mark photos keep, review, or reject 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 Process page?
ClassificationThe Process page runs indexing, species classification, feature extraction, and quality scoring for photos already in the active workspace. Use Import to add new photos; use Process when you want to run or rerun selected processing stages.
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