Skip to content

Quickstart

Start here. Five minutes from nothing to searching your own photos.

Terminal window
curl -fsSL https://videre.sh/install | sh

No Rust toolchain, nothing to compile. On macOS, brew install aegea-dev/tap/videre works too and handles upgrades for you. Both are covered in install, along with building from source and the platform notes.

Your photo folder is the library. Run videre inside it:

Terminal window
cd ~/Photos
videre scan

That builds a database at ~/Photos/.videre/hashes.db describing what you have, and everything below reads from it. It does not change your photos.

Every command acts on the library it runs in, so the rest of this page assumes you are still in ~/Photos. From anywhere else, name it explicitly with videre --library ~/Photos <command>.

Terminal window
videre dedupe # list which copies could go
videre dedupe review # ...or review them in a browser first
videre dedupe trash # move the copies to the trash (asks first)

By default videre dedupe only prints a list for you to check; trash is what actually deletes, moving the copies to the system trash after asking. --kind picks other kinds: resized for the same picture at another size, creation for Google Photos edits beside their originals, and similar for photos and videos that merely look alike (after videre embed), which are reported for review only, never removed.

Terminal window
videre embed # one-time: prepares photos for search
videre search "golden gate bridge at sunset"
videre search --image reference.jpg # find photos like this one

The first videre embed downloads about 1.5 GB of model data (Google’s SigLIP, from Hugging Face; see what gets downloaded) and takes a while on a big library. You can stop it at any point and rerun later, and it picks up where it left off.

Terminal window
videre faces # detect and group faces
videre gallery # name the groups in your browser
videre search --person "Alice"

videre faces downloads about 180 MB the first time.

Every command takes --help, and Commands is the full reference with every flag.

Each of the above is a small pipeline: search needs embed first, search --person needs faces plus naming, and prune belongs after files are deleted or moved outside videre.

Workflows has the full map, plus recipes for the common jobs and rough costs for the long ones.

Terminal window
videre classify # tag screenshots/documents/memes
videre search --category screenshot
videre locations # group photos by place
videre search --location "Berlin"
videre fix-dates # set file dates from EXIF
videre gallery # browse the whole library
videre stats # what's in the library
videre watch # keep everything fresh in the background

videre dedupe prints one file path per line, so a script can read the list. To remove the copies, use videre dedupe trash or delete rather than a pipe; for a script that must, --print0 writes the paths NUL-delimited so a path with a space survives:

Terminal window
videre dedupe > to-delete.txt # the list, to read or feed a script
videre dedupe --print0 | xargs -0 ls -l # NUL-delimited, space-safe

videre search, videre dedupe, videre stats and videre locations accept --json for scripting, and videre mcp exposes search and duplicate review to AI agents over stdio:

{
"mcpServers": {
"videre": { "command": "/path/to/videre", "args": ["mcp"] }
}
}
  • Long jobs (embed, faces, classify) are resumable. Ctrl-C is safe, and rerunning continues where it stopped.
  • Two different videre commands can run at once against the same database. Running the same command twice is refused rather than allowed to corrupt anything.
  • videre gallery starts a local web server on localhost:7878. Nothing leaves your machine.
  • The only feature that touches the network is videre search --location, which looks up a place name once and caches the result.