Publish a custom integration

A custom integration is built the same way as an integration in core. Everything in Building integrations applies: the manifest, config flows, entities, fetching data, and tests. This page only covers what is different when you publish it yourself.

For a new integration, the Marketplace is the recommended place to start, also when you want it in core one day. See does it belong in core.

One repository holds one integration, in custom_components/<domain>/:

custom_components/my_integration/__init__.py
custom_components/my_integration/manifest.json
custom_components/my_integration/sensor.py
custom_components/my_integration/translations/en.json
custom_components/my_integration/brand/icon.png
hacs.json
README.md

The Marketplace installs the first folder it finds under custom_components/, to custom_components/<domain>/ in the user's configuration folder. Every file the integration needs has to be inside that folder. The repository structure has the other layouts it accepts.

A custom integration needs two keys that integrations in core leave out:

• version: required. Without a version the loader accepts, the Marketplace refuses the install. Use the same version as the tag of your release.
• issue_tracker: where users report bugs. HACS requires it for the catalog.

documentation points to your own documentation, like your README. The manifest reference has the details.

Only list requirements that are not already requirements of Home Assistant itself.

The domain is the folder name, and what Home Assistant knows your integration by. Pick one that no integration in core uses.

A custom integration with the domain of a built-in one replaces it. Home Assistant allows that, but the user loses the updates of the built-in one, and the Marketplace asks the user to confirm before such an install. The catalog does not accept integrations that replace a core integration. Users can still add them from a link.

Two repositories can not install the same domain. When a user has one installed, the Marketplace refuses the other.

Custom integrations do not use strings.json, and are not translated on Lokalise. Ship the finished files in translations/, with a complete en.json. See translations for custom integrations.

Put your icon and logo in a brand/ folder inside the integration folder. Home Assistant shows them once your integration is installed. The Marketplace also shows them before that: the brands site picks them up from the latest release of every integration in the catalog.

Do not use Home Assistant branded images. Users would take your integration for an official one. The brands page has the image names and sizes.

An update replaces the whole integration folder. If your integration writes files there that the user needs to keep, put them in one subfolder, and name it in hacs.json:

{
  "name": "My integration",
  "persistent_directory": "userfiles"
}

The Marketplace moves that folder out of the way during an update, and puts it back after.

On a first install, an integration with a config flow loads right away, so the user can add it without a restart. An integration set up in YAML needs a restart, and so does every update or removal of an integration that Home Assistant already loaded. The Marketplace creates a repair for that, with a button to restart.

Once your integration is installed, a My link can take users straight to its setup. The config_flow_start link starts the config flow of the domain you give it, in the user's own Home Assistant. The My link creator makes the badge for your README:

[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=my_integration)

To link to your repository in the Marketplace, so users can install it first, see the link to your repository.

Run two GitHub Actions on every push and pull request:

• hassfest checks your manifest, translations, and other files of your integration.
• The HACS action with category: "integration" checks what the catalog needs. See validation checks.

Both have to pass to get into the catalog.

Changes in core can break a custom integration. Changes to what custom integrations use from core, like helpers, constants, and entity properties, are deprecated for 12 months first, and announced on the blog. The deprecation policy has the details. Test your integration against the beta, and set homeassistant in hacs.json when a release needs a newer Home Assistant. See releases and updates.

The integration quality scale has no tiers for custom integrations, but its rules are still a good guide.

Once your integration has matured and has a user base, reach out to the maintainers, for example in the #core channel on Discord, to see whether it should ship built in. Does it belong in core lists what core asks for, and every new integration in core needs the Bronze rules of the quality scale.

Some differences on this page turn around in core. For example, the brand images go to the brands repository, and the translations come from strings.json.