Packages as a default part of the yaml based configuration

Disclaimer: I am posting this here mainly because I saw discussions about this in the community here far too often and I want a topic to reference people to.

Disclaimer 2: This suggestion does not stand in conflict with the new concept of labels etc but rather works in parallel. It would be amazing if a future improvement merges the concept of packages and labels.

Feature Request:

Please consider adding an included packages folder to the default yaml configuration for new setups.


  • New users relying on the UI to configure their setup will not be harmed by it
  • Users comfortable to work in yaml will benefit from this addition as a feature they may but do not have to use.

It should also be considered that many snippets here in the community assume a packages based setup and users are regularly confused by that.

Justification and implementation today:

A quickly growing yaml-based configuration can become confusing and hard to maintain. It is, therefore, useful to follow a use-case driven approach by structuring your configuration by topics like heating, night-light or garage-door-automation. These “packages” are independent files and make management and troubleshooting a lot simpler. This approach can nowadays also be found in the UI configuration with “labels”.

In short, enable packages in your <HomeAssistantConfig>/configuration.yaml like this:

  packages: !include_dir_named packages

Then move your topic specific configuration elements into files like <HomeAssistantConfig>/packages/heating-or-something.yaml The file configuration.yaml will stay unchanged going forward.

More details on packages:

I would expect everyone that has moved past the UI to start even the simplest YAML code would be able to add that themselves. Certainly the custom_integration developer could add the instructions should they decide to provide their stuff in a package.
No, packages are not that hard, but they are advanced enough that you have to understand things a bit to be able to use them.


Many configuration example are compatible with packages, but I think it’s incorrect to say that it is assumed that is the method being used. The convention in the docs is to have configuration examples formatted as if it is being adding to a fresh configuration.yaml. That convention followed along onto the forums (though it is not enforced). If anything, the percentage of examples that follow the convention have drastically decreased since the introduction of the UI automation editor and as more and more integrations have moved to the UI.

Not incorrect but (1) they need to randomly find out about the concept, (2) look up the syntax and put it to the test, (3) de-clutter their configuration.yaml which has gotten messy from their early attempts, and (4) I would disagree that they are “advanced”. In my opinion every user should start out with packages and the documentation should encourage that. Easiest way to do that is to provide a starting point with the default config (similar to e.g. groups.yaml).

Without getting too philosophical I think we can agree that everything we commonly see as snippets in the community and the docs could easily be copy-pasted into a new test.yaml package file while it would be tedious to add them in a monolithic configuration.yaml

Just to emphasize this again: You can find incidents in which community members had issues or headaches with their yaml configuration due to the lack of a proper configuration structure everywhere. I’ve responded to quite a few of such myself. I have yet to see a advanced yaml user who has implemented another configuration structures in a sane way :slight_smile:

This discussion is to encourage the use of packages and a wish to add the concept as part of the default configuration.

1 Like

It’s fine to encourage the use of packages. I use them quite a bit - tho also not exclusively. I have many domains/platforms which I use !includes to incorporate on a case-by-case basis for however it logically makes sense to group things.

For example if a sensor is part of a larger system that needs other domains to function I put the sensor in a package with the other stuff. If it’s a one-off standalone entity then it gets incorporated using !include.

I also doubt that this will be added to the default config since yaml (by definition due to the current trajectory of the project) is considered “advanced”.

Not sure why you would use “advanced” as an argument against this. The HA developers want to address the needs of all users and make HA comfortable to use for everyone. Given, it is important to lure in new users with a pretty UI but users growing their setup will not stay without any YAML code. certainly welcome a world in which more and more can be solved right from the UI but those yaml edge cases will remain. In any case, packages are a useful default to provide.

1 Like

I don’t think you’ve been following the trajectory of this project.

the developers have deemed almost everythinbg that isn’t configurable via the UI as “advanced”.

I don’t disagree with this statement at all.

But that does kind of prove the point - as users get more “advanced” then they will eventually start using the UI for configuration less and less (unless they are forced to use the UI because there is no equivalent yaml config functionality - which again is more and more becoming the standard).

at that point the (now “advanced”) users will understand how to use packages because they understand the usage scenarios and how to configure them.