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.
Detailed guides
Understand every decision
Visual, task-oriented references for Vireo's most powerful workflows.
Review encounters, predictions, and grouping
Learn how to narrow a large review without losing context, resolve species disagreements, work with multiple models, and correct burst or encounter boundaries.
Read the detailed guideFAQ
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.
How do I filter photos?
BrowsingEvery photo page (Browse, Map, Review, Duplicates) shares one filter bar. Start typing in the search box to filter text matches immediately. Rating, flag, and color quick filters are always visible below the search box; open Filters for a rule builder over every metadata field — camera, lens, ISO, capture date (including “in the last N months”), species, and more. Active filters appear as chips you can remove individually; the dashed chip shows the page's fixed scope. Flags and colors multi-select into a single “is one of” rule, and typed values suggest real values from your library with live match counts.
How do I search photos visually?
BrowsingType a description in the filter bar's search box and choose “✦ Visually similar to …” from the suggestion menu. The visual clause appears as a purple chip, combines with your other filters, and offers broad/balanced/strict strength in the Filters popover. If visual search can't run (no active model, or no visual index yet), the chip shows an error state and your metadata filters keep working — results are never silently empty.
How do I temporarily disable my filters?
BrowsingPress \ (backslash) or click Pause in the filter bar. All filters are disabled without being lost — chips dim, and a note reports how many photos would match. Press \ again or click Resume to re-apply them. The paused state persists per workspace.
How do I save my filters as a Collection?
BrowsingOpen Filters and click “Save as Collection…”. The saved Collection stores your full expression — including a visual search clause if one is active (marked with ✦ in the sidebar). Clicking a Collection opens its rules back into the filter bar as editable chips, so you can refine it and re-save.
Looking for more?
For technical documentation, troubleshooting, developer interfaces, and contributing guidelines, visit the project on GitHub.
View on GitHub