Packages

Packages in Home Assistant provide a way to bundle configurations from multiple integrations. You can use packages to include multiple integrations, or parts of integrations, using any of the !include directives introduced in splitting the configuration.

Packages are configured under the core homeassistant/packages in the configuration and take the format of a package name (no spaces, all lowercase) followed by a dictionary with the package configuration. For example, package pack_1 would be created as:

homeassistant:
  ...
  packages:
    pack_1:
      ...package configuration here...

The package configuration can include: switch, light, automation, groups, or most other Home Assistant integrations including hardware platforms.

It can be specified inline or in a separate YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] file using !include.

Inline example, main configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

homeassistant:
  ...
  packages:
    pack_1:
      switch:
        - platform: rest
          ...
      light:
        - platform: rpi
          ...

Include example, main configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

homeassistant:
  ...
  packages:
    pack_1: !include my_package.yaml

The file my_package.yaml contains the “top-level” configuration:

switch:
  - platform: rest
    ...
light:
  - platform: rpi
    ...

There are some rules for packages that will be merged:

1. Platform based integrations (light, switch, etc) can always be merged.

2. Integrations where entities are identified by a key that will represent the entity_id ({key: config}) need to have unique ‘keys’ between packages and the main configuration file.

   For example, if we have the following in the main configuration. You are not allowed to re-use “my_input” again for input_boolean in a package:

   input_boolean:
     my_input:
   

3. Any integration that is not a platform [1], or dictionaries with Entity ID keys [2] can only be merged if its keys, except those for lists, are solely defined once.

Create a packages folder

One way to organize packages is to create a folder named “packages” in your Home Assistant configuration directory. In this packages folder, you can store any number of packages in YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] files, and organize those packages into YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] files and subfolders as you see fit. With !include_dir_named, the filename is used as the package name. This means that file names must be globally unique, even across subfolders. This entry in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] will load all YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more]-files in this packages folder and its sub folders:

homeassistant:
  packages: !include_dir_named packages

The benefit of this approach is to pull all configurations required to integrate a system into one file, rather than keeping them spread across several files.

You can also use !include_dir_merge_named for packages. The two directives differ in how they handle the file contents. With !include_dir_named, each file’s content is placed directly under the package name (which is the filename), so the content uses the same indentation as it would inside the packages: key in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]. This means you can copy and paste elements from the main config file. With !include_dir_merge_named, the package name has to be the top-level key inside the file, so the content needs an additional level of indentation and you cannot directly copy and paste from the configuration file.

homeassistant:
  packages: !include_dir_merge_named packages

and in packages/subsystem1/functionality1.yaml:

subsystem1_functionality1:
  input_boolean:
  ...
  binary_sensor:
  ...
  automation:

Customizing entities with packages

It is possible to customize entities within packages. Just create your customization entries under:

homeassistant:
  customize: