Skip to content

Getting Started

Installation

You need Python 3.10–3.14 installed to be able to use the CLI.

curl -LsSf uvx.sh/immichpy/install.sh | sh -s -- --with immichpy[cli]

Info

This installs uv under the hood. See uvx.sh for more information.

Within a project…:

uv add immichpy --extra cli

…or globally:

uv tool install immichpy[cli]

pip install immichpy[cli]

Shell completion

Install shell completion for easier command-line usage. The command auto-detects the shell and installs the completion for it.

immichpy --install-completion
fish completion installed in ~/.config/fish/completions/immichpy.fish
Completion will take effect once you restart the terminal

You will get auto-completion for the commands and options when hitting the Tab key.

Setup

  1. Have your Immich server running or use the demo server.
  2. Get an API key from your Immich account settings.

Create a profile

Using profiles allows you to use the CLI with different servers and reuse configurations easily.

immichpy setup# Enter your server URL: $ https://demo.immich.app/api# Enter your API key: $ ********
Profile 'default' created successfully!

Validation

The server is validated when you run immichpy setup. The validation will fail by default if the server is not reachable.

See immichpy setup for the full command reference.

First commands

That's it! You can now interact with the Immich server using the CLI.

immichpy server get-about-info
{
"build": "20375083601",
"version": "v2.4.1",
}

You can also get the information in a different format, e.g. as a table:

immichpy --format table server get-about-info
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Key ┃ Value ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ build │ 20375083601 │
│ version │ v2.4.1 │
└──────────┴────────────────┘

To see all available commands, run immichpy --help or see the reference.