2026.6.3
Home ▸ Integrations

Immich

This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] 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.

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

Important

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

Configuration

To add the Immich service 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).

List of actions

The Immich integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

  • Upload file (immich.upload_file) Uploads a file to your Immich instance.

For an overview of every action across all integrations, see the actions reference.

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.

Known limitations

There are no known limitations.

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.