immich-sdk

Python SDK for the Immich API. Type-safe client generated from the official OpenAPI specification, with support for albums, assets, authentication, libraries, and all other Immich API endpoints.

• Official API documentation: Immich API
• OpenAPI / developer docs: Immich OpenAPI

Table of Contents

• Prerequisites
• Installation
  • Install uv
    • Linux
    • macOS
    • Windows
  • Install the SDK
  • Pre-commit (development)
• Quick Start

Prerequisites

• Python 3.13 or later. The SDK requires Python 3.13+.
• uv for dependency management and virtual environments. uv is a fast, drop-in replacement for pip and pip-tools.

Installation

Install uv

Install uv using one of the methods below for your platform. See Installation - uv for more options.

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Add ~/.local/bin to your PATH if it is not already there (the installer will print instructions).

macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

On macOS you can also install via Homebrew:

brew install uv

Windows

Using PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, restart your terminal. The installer adds uv to your user PATH.

Install the SDK

Clone the repository and sync dependencies with uv:

git clone https://github.com/bueckerlars/immich-sdk.git
cd immich-sdk
uv sync

This creates a virtual environment (e.g. .venv) and installs the package and its dependencies. To install with development dependencies (testing, linting, pre-commit):

uv sync --extra dev

Pre-commit (development)

For contributors: install the pre-commit hooks so that formatting and linting run automatically before each commit.

After cloning and running uv sync --extra dev:

pre-commit install

Pre-commit will then run hooks (e.g. Ruff, Black, pyupgrade, toml-sort) on staged files. To run manually:

pre-commit run --all-files

Quick Start

from immich_sdk import ImmichClient

client = ImmichClient(
    base_url="https://immich.example.com",
    api_key="your-api-key",
)

# Use sub-clients for each API area
albums = client.albums.get_all()
assets = client.assets.get_all()

Authentication uses the x-api-key header. Create an API key in Immich under Settings > API Keys. For more endpoints and request/response formats, see the official Immich API documentation.