home-assistant.io/source/_docs/configuration/packages.markdown

title, description

title	description
Packages	Describes all there is to know about configuration packages in Home Assistant.

Packages in Home Assistant provide a way to bundle different component's configuration together. With packages we have a way to include different components, or different configuration parts 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 lower case) 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 YAML file using !include.

Inline example, main configuration.yaml:

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

Include example, main configuration.yaml:

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. Components 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.

Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the integration name.

Create a packages folder

One way to organize packages is to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a YAML file. This entry in your configuration.yaml will load all packages:

homeassistant:
  packages: !include_dir_named packages

This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames. See the documentation about splitting the configuration for more information about !include_dir_named and other include statements that might be helpful. The benefit of this approach is to pull all configurations required to integrate a system, into one file, rather than across several.

The following example allows to have subfolders in the packages folder, which could make managing multiple packages easier by grouping:

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: