2025.8.3
Home ▸ Integrations ▸

Immich

This integration allows adding an Immich user account to Home Assistant.

Prerequisites

You need to obtain the API key for your user account in your Immich instance.

API key permissions

Enable the following permissions when creating your API key. Without these permissions, the integration may not work properly. The “admin-only” permissions are only available when your API key belongs to an administrative user.

  • album.read
  • albumAsset.create
  • asset.upload
  • asset.view
  • person.read
  • server.about
  • server.statistics (admin-only)
  • server.storage
  • server.versionCheck
  • tag.read
  • user.read

Important

Prior to immich server version 1.138.0 the all permission is necessary for your API key.

Configuration

To add the Immich integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

URL

The URL of your Immich instance. (e.g. https://immich.example.com).

API key

API key of your user account to connect to your Immich instance.

Verify SSL certificate

Whether to verify the SSL certificate when SSL encryption is used to connect to your Immich instance.

Data fetching

The integration polls data every 60 seconds.

Media source

A media source is provided for your Immich albums. It shows only the assets you own or that are shared with you. If you have multiple Immich integrations in Home Assistant (one integration for each Immich user), only the assets for that specific user are shown. The assets are grouped by albums, people, and tags.

Sensors

The following sensorsSensors return information about a thing, for instance the level of water in a tank. [Learn more] are created. For some of those the API key needs to have admin rights.

Entity Description Default enabled
Disk size Overall size of the disk ✅
Disk available Free space on the disk ✅
Disk used Used space on the disk ❌
Disk usage Usage of the disk in percentage ❌
Photos count Count of stored photos (admin only) ✅
Videos count Count of stored videos (admin only) ✅
Disk used by photos Used disk space by photos (admin only) ❌
Disk used by videos Used disk space by videos (admin only) ❌

Update entity

An updateAn update entity is an entity that indicates if an update is available for a device or service. [Learn more] entity is created to inform about a new available Immich server version (requires Immich server v1.134.0).

Actions

Upload file

This action allows you to upload a media file to your Immich instance. It takes the following arguments:

Immich instance

The config entry of the Immich instance where to upload the file.

File

Use the MediaSelector to define the file to be uploaded.

media_content_id

The media source URL.

media_content_type

The MIME type of the file to be uploaded.

Album ID

The album in which the file should be placed after uploading. To get the album ID, open the Immich instance web UI in a browser and navigate to the corresponding album, the album ID can now be found in the URL https://your-immich-instance/albums/<ALBUM-ID>

Example script

Take a snapshot of a camera entity via the camera.snapshot action, use the local media path to store the snapshot and upload it to the Immich instance in a specific album.

sequence:
  - variables:
      file_name: camera.yourcamera_{{ now().strftime("%Y%m%d-%H%M%S") }}.jpg
  - action: camera.snapshot
    data:
      filename: "/media/{{ file_name }}"
    target:
      entity_id: camera.yourcamera
  - action: immich.upload_file
    data:
      config_entry_id: 01JVJ0RA387MWA938VE8HGXBMJ
      file:
        media_content_id: "media-source://media_source/local/{{ file_name }}",
        media_content_type: "image/jpeg",
      album_id: f2de0ede-d7d4-4db3-afe3-7288f4e65bb1

Troubleshooting

In any case, when reporting an issue, please enable debug logging, restart the integration, and as soon as the issue re-occurs, stop the debug logging again (download of debug log file will start automatically). Further, if still possible, please also download the diagnostics data. If you have collected the debug log and the diagnostics data, provide them with the issue report.

Remove the integration

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three dots menu. Then, select Delete.

If the API key is not used anymore, you can remove it from your Immich instance.