Photovault

How-to

Everything you need to install the scanner on macOS, Linux, or Windows — then to connect Google Photos.

Install the scanner · Connect Google Photos

Install the scanner

Lighter than the desktop bundle — installs the same photovault CLI and the photovault gui window. Three prerequisites: Python 3.10+, Tk (for the GUI), and GnuPG.

macOS (Homebrew)

brew install python python-tk pipx gnupg
pipx install photovault

python-tk is critical — Homebrew's Python doesn't ship Tk by default and photovault gui won't launch without it.

Linux — Debian / Ubuntu

sudo apt install -y python3-tk pipx gnupg
pipx install photovault

Linux — Fedora / RHEL

sudo dnf install -y python3-tkinter pipx gnupg2
pipx install photovault

Linux — Arch / Manjaro

sudo pacman -S python python-pipx tk gnupg
pipx install photovault

Windows (winget)

winget install Python.Python.3 GnuPG.Gpg4win
python -m pip install --user pipx
pipx ensurepath
pipx install photovault

Python.org's Windows installer ships Tk by default, so no separate package needed. Restart your shell after pipx ensurepath so the photovault command is on PATH.

Then on any OS

photovault login --server https://photovault.traeck.it --username YOUR_NAME
photovault gui                       # open the window
photovault scan-photos --dry-run     # or run a CLI scan

Also on PyPI and Bitbucket.

Connect Google Photos

Google's Photos Library API was restricted in 2025 — third-party apps can no longer read your existing Google Photos library. There are two paths Photovault supports, each with trade-offs.

1. Takeout (the full library)

Slow (Google takes hours to days to assemble the archive), but the only way to get your entire Google Photos library. Asynchronous — Google emails you when the zip is ready.

  1. Open Google Takeout.
  2. Click Deselect all, scroll down to Google Photos, tick only that.
  3. Click Next step. Defaults are fine (.zip, 50 GB chunks, "Send download link via email").
  4. Click Create export and wait for the email. Big libraries can take days and arrive as multiple zips.
  5. Download every zip and extract them into one folder: 
    cd ~/Downloads
mkdir -p ~/Takeout-Photos
for z in takeout-*.zip; do unzip -q "$z" -d ~/Takeout-Photos; done
  6. Open the Photovault app, pick Google Photos (Takeout export), point Browse at ~/Takeout-Photos/Takeout/Google Photos/, click Start scan.

Each photo arrives with a sibling .json sidecar that Photovault auto-reads for the original capture date — so dates survive even if EXIF is missing.

2. Picker (add as you go)

Interactive — you tap photos in a Google-hosted picker and Photovault grabs just those. Up to ~500 photos per session. Best for "save these vacation pics" rather than full-library backup.

  1. One-time setup: create a Google Cloud project + OAuth client.
    • Open create a project; name it anything (e.g. photovault-picker).
    • Enable the Photos Picker API in APIs & Services → Library.
    • Configure OAuth consent screen as External, Testing mode, add your Google address as a test user.
    • Create credentials → OAuth client ID → Desktop app. Copy the Client ID and Client Secret.
  2. In the Photovault app, pick Google Photos (live picker) and click Configure Google….
  3. Paste the Client ID + Client Secret, click Save & sign in. Your browser opens for Google consent.
  4. Click Start scan. Your browser re-opens to Google's picker; tap photos, click Done, Photovault downloads + encrypts + uploads them.

OAuth tokens stay in your macOS Keychain. The Client ID/Secret are for your Google Cloud project — Photovault has no centralised Google integration.

Why both? Google's 2025 API restrictions removed the surface that would let an app sync your full library automatically. Takeout is the only complete-backup path; the Picker is the only live-from-Google path.