Install

Install script

One command, no Rust toolchain, nothing to compile:

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

It works out your platform, downloads the matching release, verifies it against the .sha256 published with that release before unpacking it, and puts the binary in ~/.local/bin. If that directory is not on your PATH it prints the line to add. It never edits your shell profile.

Option
--version X.Y.Z	Install a specific release rather than the latest
--to DIR	Install somewhere other than ~/.local/bin
--uninstall	Remove the binary the script installed
--help	Show usage

Pass options after -s --:

curl -fsSL https://videre.sh/install | sh -s -- --version 0.20.1

-s -- is the same in every shell

Everything after the pipe is parsed by sh, not by the shell you typed the line into, so -s -- behaves identically in fish, zsh and bash. -s tells sh to read the script from the pipe, and -- ends sh’s own options so the rest reach the installer.

Upgrading

Run the same command again:

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

It fetches the newest release and overwrites the binary in place. There is nothing to uninstall first, and your library, settings and downloaded models are untouched. Check it took with videre --version.

Nothing tells you an update exists

The script never checks for one and videre does not phone home, so upgrading is something you do rather than something you are prompted about. If you would rather not think about it, Homebrew handles upgrades: brew upgrade videre.

Going back is the same command with a version:

curl -fsSL https://videre.sh/install | sh -s -- --version 0.20.0

Removing it

curl -fsSL https://videre.sh/install | sh -s -- --uninstall

This removes one file, the binary the script installed. Your library and the downloaded models are left exactly where they are, and the script prints both paths with their sizes so you can remove them yourself if you want to:

• <library>/.videre/ holds the database, your config and the search embeddings. An embedding costs hours to recompute, so nothing here is deleted for you.
• ~/.cache/huggingface/ holds the models, and is shared with any other tool that uses the Hugging Face cache.

If the videre it finds was installed by Homebrew or cargo, the script refuses to delete it and tells you the right command instead. Removing a package manager’s file behind its back leaves it believing videre is still installed.

Homebrew

The best option on macOS, because it handles upgrades:

brew install erhangundogan/tap/videre

Prebuilt binary

Download from the latest release and put it on your PATH. No Rust toolchain needed, nothing to compile.

Platform	File
Apple Silicon Mac	videre-<version>-aarch64-apple-darwin.tar.gz
Linux x86_64	videre-<version>-x86_64-unknown-linux-gnu.tar.gz
Linux ARM64	videre-<version>-aarch64-unknown-linux-gnu.tar.gz

tar xzf videre-*-aarch64-apple-darwin.tar.gz
./videre --version

Each archive has a .sha256 alongside it.

Gatekeeper on macOS

A binary downloaded with a browser is quarantined by macOS. Either download it with curl, or clear the flag:

xattr -d com.apple.quarantine videre

Homebrew installs are not quarantined, so brew install avoids this entirely.

More than one videre will shadow itself

If you have installed videre more than one way, whichever copy comes first on your PATH wins, and videre --version quietly reports that one. An old cargo install videre in ~/.cargo/bin is the usual culprit.

which videre          # check which copy you are actually running

Troubleshooting lists where each install method puts the binary and how to remove each one properly.

From source

Needs a Rust toolchain.

cargo install videre

git clone git@github.com:erhangundogan/videre.git
cd videre
cargo build --release

On ARM64 Linux, building from source needs one extra flag. The released binary does not, since it is already built with it:

RUSTFLAGS="-C target-feature=+fp16" cargo install videre

Without it the build fails with error: instruction requires: fullfp16. This is the main reason to prefer the install script on ARM64 Linux: it fetches a binary that already has the flag baked in, so the problem never arises.

Platform notes

Intel Macs are not supported. The ONNX Runtime dependency ships no prebuilt binaries for x86_64-apple-darwin, so videre cannot be built there at all, including via cargo install.

macOS is the primary platform. videre also runs on Linux, with one gap: HEIC photos and video frames are decoded using a macOS system tool, so on Linux those files are skipped (with a clear message) for thumbnails, search, and face detection. They are still scanned, hashed, and de-duplicated. JPEG, PNG and friends work everywhere.

See platform support for the per-command matrix.

Models are not downloaded at install

Nothing is downloaded until you run a command that needs it. Scanning, de-duplicating, fixing dates, pruning and stats work with no model at all.

Two commands need machine-learning models, and each fetches its own from Hugging Face the first time you run it:

Command	Model	What it is	Size
videre embed	google/siglip2-base-patch16-224	SigLIP 2, Google’s image/text model. Turns a photo and a phrase into comparable vectors, which is what makes “sunset over water” match a picture.	~1.5 GB
videre faces	WePrompt/buffalo_l	InsightFace buffalo_l, two ONNX models: det_10g.onnx (SCRFD) finds faces, w600k_r50.onnx (ArcFace) turns each face into a vector so matching ones can be grouped.	~180 MB

Both downloads are resumable, so you can stop and rerun.

They are only fetched once and then reused, including by later runs against a different library. The download happens at the start of the run, before any of your photos are processed.

The gallery Map view also downloads a world map archive the first time you open /map: a vector basemap (coastlines and borders) built from OpenStreetMap data by Protomaps, stored once in the shared cache and used offline afterward. It is resumable and shared across libraries, and no map or tile request is made once it is present. Until it finishes, the map still works from your own location clusters. The map renders it with MapLibre GL JS, with © OpenStreetMap contributors shown on the map.

Where they are stored

In the standard Hugging Face cache, shared with any other tool that uses it:

~/.cache/huggingface/hub/

Set HF_HOME to put it elsewhere. This is separate from videre’s own directory, so removing a library’s .videre/ does not delete the models, and deleting the cache means the next embed or faces run downloads them again.

Bigger models are opt-in

The table above is the default. If you select a different search model, it is fetched instead: siglip2-base-patch16-384 is about 1.5 GB and siglip2-so400m-patch14-384 about 4.5 GB. Nothing downloads them unless you ask for them by name.

Nothing is uploaded

These are downloads only. The models run on your machine, and your photos are never sent anywhere. Two features make an outbound request: videre search --location, which looks up a place name, and the gallery Map view, which downloads a world basemap once on first use (below). Both fetch data in; neither sends anything about your library out.

Shell completion

Tab completion installs itself. The first time videre runs under bash or fish, it writes a completion script into the directory that shell already loads (~/.local/share/bash-completion/completions/ and ~/.config/fish/completions/), and refreshes it when the version changes. Open a new shell (or re-source your setup) and tab completes subcommands, flags, and choices such as --xmp db|file|newest.

zsh has no per-user completion directory on its load path, so it is not installed automatically. Save the script as _videre in a directory on your fpath - for oh-my-zsh, ~/.oh-my-zsh/completions/_videre - and run rehash:

videre completion zsh > ~/.oh-my-zsh/completions/_videre && rehash

With --person, --model, --tag, --category, --label, --ext and --mime, the value of videre config set (the three provided models for model, and the fixed choices of the others), and inside a query, the choices come from your library: register the dynamic completer in your shell’s startup file, e.g. for bash eval "$(COMPLETE=bash videre)" (zsh: eval "$(COMPLETE=zsh videre)", fish: COMPLETE=fish videre | source), and keep it read-only fast - videre answers from a read-only connection and completes nothing when there is no library.