Getting started¶
Requirements¶
- Python 3.13 or newer
- Access to a running Immich server
- An Immich API key (Account → API Keys in the Immich web UI)
pymmich runs on Linux, Windows, and macOS.
Install¶
From PyPI¶
pip install pymmich
One-off run via uvx¶
If you already have uv you can skip installation and run pymmich directly:
uvx pymmich --help
Authenticate¶
pymmich reads its credentials from two environment variables:
export PYMMICH_URL="https://immich.example.com"
export PYMMICH_API_KEY="your-api-key-here"
If either is unset, pymmich exits with an error — it will not guess.
Verifying the connection
If you want to check that the credentials work before uploading anything real, try a harmless download with a pattern that won't match:
pymmich download "__definitely_not_there__"
A credentials problem surfaces with a clear 4xx/5xx error.
First upload¶
Upload the current directory as an album:
pymmich upload . --recursive
The album name defaults to the directory's base name. See Upload for the full option list.
First download¶
Pull an album back:
pymmich download "My Album" --out ./restore
See Download for more.