Getting started¶

Requirements¶

Python 3.13 or newer
Access to a running Immich server, version 2.7 or newer — including 3.0 and 3.1
An Immich API key (Account → API Keys in the Immich web UI)

pymmich runs on Linux, Windows, and macOS.

Immich 2.x and 3.x

Immich 3.0 changed several of the endpoints pymmich uses. pymmich detects the server version on first use and adapts automatically — there is nothing to configure. See Server compatibility for the details.

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.