immich 1.4.1

Unofficial Python client for Immich

Immich API Client

Unofficial Python client for the Immich API.

[!IMPORTANT] This repository is mostly auto-generated from the Immich OpenAPI specification. Pull requests are welcome, but modifications to auto-generated code (especially immich/client/) will be rejected. See CONTRIBUTING for more details.

Status

• Unofficial: Not affiliated with or endorsed by Immich.
• Auto-synced: Kept in sync with the latest Immich release (regenerated as upstream changes land).

Installation

You need Python 3.10–3.14 installed to be able to use this library.

Install the latest stable version from PyPI:

pip install immich

If you want the latest version (which may be a pre-release):

pip install --pre immich

Structure

This SDK is async-only. The client exposes API groups as attributes, and endpoints as methods on those groups. Groups and endpoints are documented in the Immich API documentation.

Custom functions

Some API groups include custom convenience methods that are preferred over the auto-generated ones for common operations:

Assets API

• assets.download_asset_to_file: Download an asset (original file) directly to disk.
• assets.view_asset_to_file: Download an asset thumbnail directly to disk .
• assets.play_asset_video_to_file: Download an asset video stream directly to disk.

Resumable Downloads: All asset download methods support automatic resumable downloads. If a download is interrupted, the client will automatically resume from where it left off using HTTP Range requests. Partial downloads are saved as .temp files and renamed upon successful completion.

Download API

• download.download_archive_to_file: Download asset archives (ZIP files) directly to disk. You can download whole albums or user-specified assets in a single request.

Note: Archive downloads (ZIP files) do not support resumable downloads due to the nature of streaming archives.

Users API

• users.get_profile_image_to_file: Download a user's profile image directly to disk.

Authentication

Immich supports API keys. Create one in your server and pass it via api_key=.... Cookie and Bearer tokens are also supported.

Usage

With a context manager (recommended):

from immich import AsyncClient

async with AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api") as client:
    await client.server.get_about_info()

Without a context manager:

import asyncio
from immich import AsyncClient

async def main():
    client = AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api")
    try:
        await client.server.get_about_info()
    finally:
        await client.close()

asyncio.run(main())

Response Types

There are three different available output formats you can choose from:

Serialized Response

You can get fully serialized responses as Pydantic models. Using this, you get the full benefits of Pydantic's type checking.

res = await client.server.get_about_info()

The output would look like this:

ServerAboutResponseDto(...)

Serialized Response with HTTP Info

res = await client.server.get_about_info_with_http_info()

The output would look like this:

status_code=200 headers={'Content-Type': 'application/json'} data=ServerAboutResponseDto(...) raw_data=b'{"...": "..."}'

JSON Response

You can receive a classical JSON response by suffixing the function name with _without_preload_content:

response = await client.server.get_about_info_without_preload_content()
await response.json()

Session management

The client can manage a shared aiohttp.ClientSession, or you can pass your own via http_client=... (you are responsible for its lifecycle).

Versioning

This package follows Semantic Versioning.

• Package version is not the server version: immich package X.Y.Z is the client’s own version.
• Upstream breaking changes ⇒ major bump: Breaking Immich changes that require breaking client changes produce a new major version.
• Supported Immich server version: IMMICH-VERSION (repo root) tracks the Immich version this client was generated from.
  • If you run an older Immich server version, you can install an older immich package release where IMMICH-VERSION matches your server.
  • This client supports Immich v2.4.1 and above.