NixOS Wiki

Home Assistant: Difference between revisions

← Older edit
VisualWikitext
Sandro (talk | contribs)
53 edits
fix typoi´
Hexa (talk | contribs)
50 edits
Update component support numbers for 2025.4,2
 
(13 intermediate revisions by 6 users not shown)
Line 5: Line 5:
NixOS provides native support for [https://www.home-assistant.io/faq/ha-vs-hassio/ Home Assistant Core] and offers integration facilities for most pieces of its comprehensive ecosystem:
NixOS provides native support for [https://www.home-assistant.io/faq/ha-vs-hassio/ Home Assistant Core] and offers integration facilities for most pieces of its comprehensive ecosystem:


* As of the 2024.7.3 release we support roughly 88.4% (1117/1264) of the built-in integrations
* As of the 2025.4.2 release we support roughly 91.96% (1224/1331) of the built-in integrations
* We support [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-components custom components] through the <code>[https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customComponents services.home-assistant.customComponents]</code> option
* We support [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-components custom components] through the <code>[https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customComponents services.home-assistant.customComponents]</code> option
* We support source-built [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-lovelace-modules custom lovelace modules] mostly through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules services.home-assistant.customLovelaceModules] option
* We support source-built [https://github.com/NixOS/nixpkgs/tree/master/pkgs/servers/home-assistant/custom-lovelace-modules custom lovelace modules] mostly through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules services.home-assistant.customLovelaceModules] option
* We do not support [https://www.home-assistant.io/addons/ addons], which are used to deploy additional services, that are configurable from Home Assistant on their operating system
* We do not support [https://www.home-assistant.io/addons/ addons], which are used to deploy additional services, that are configurable from Home Assistant on their operating system
** NixOS has native support for various services, that integrate with Home Assistant, e.g. [[Mosquitto]], [[Wyoming]], [[zigbee2mqtt]], [[Z-Wave JS]]
** NixOS has native support for various services, that integrate with Home Assistant, e.g. [[Mosquitto]], [[Music-Assistant]], [[Wyoming]], [[zigbee2mqtt]], [[Z-Wave JS]]


== Support ==
== Support ==
Line 55: Line 55:
== Native installation ==
== Native installation ==


* There is full support for configuring the through the <code>[https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.config services.home-assistant.config]</code> option.
* There is full support for the YAML configuration through the <code>[https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.config services.home-assistant.config]</code> option.
* This is also the case for the [https://www.home-assistant.io/dashboards/dashboards/#adding-more-dashboards-with-yaml Lovelace YAML configuration] through the [https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.lovelace <code>services.home-assistant.lovelace</code>] option.
* This is also the case for the [https://www.home-assistant.io/dashboards/dashboards/#adding-more-dashboards-with-yaml Lovelace YAML configuration] through the [https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.lovelace <code>services.home-assistant.lovelace</code>] option.
** Custom Lovelace modules can be configured through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules <code>services.home-assistant.customLovelaceModules</code>]. The [https://www.home-assistant.io/dashboards/dashboards/#resources <code>resources</code>] section of your Lovelace configuration will automatically be populated.
** Custom Lovelace modules can be configured through [https://search.nixos.org/options?channel=unstable&show=services.home-assistant.customLovelaceModules&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.customLovelaceModules <code>services.home-assistant.customLovelaceModules</code>]. The [https://www.home-assistant.io/dashboards/dashboards/#resources <code>resources</code>] section of your Lovelace configuration will automatically be populated.
Line 65: Line 65:
The following is a minimal configuration, that has all the dependencies that are required to complete the initial configuration flow, that creates your first user:
The following is a minimal configuration, that has all the dependencies that are required to complete the initial configuration flow, that creates your first user:


<syntaxHighlight lang=nix>
<syntaxhighlight lang="nix">
{
{
   services.home-assistant = {
   services.home-assistant = {
Line 71: Line 71:
     extraComponents = [
     extraComponents = [
       # Components required to complete the onboarding
       # Components required to complete the onboarding
       "esphome"
       "analytics"
      "google_translate"
       "met"
       "met"
       "radio_browser"
       "radio_browser"
      "shopping_list"
      # Recommended for fast zlib compression
      # https://www.home-assistant.io/integrations/isal
      "isal"
     ];
     ];
     config = {
     config = {
Line 82: Line 87:
   };
   };
}
}
</syntaxHighlight>
</syntaxhighlight>


=== Imperative configuration ===
=== Imperative configuration ===
Line 106: Line 111:


=== Firewalling ===
=== Firewalling ===
If not using a reverse-proxy, and you just want unencrypted access on a local network don't forget to update your firewall configuration to expose the port home-assistant is running on.
Home Assistant by default listens on port 8123. It is customary to put services behind a [[Home Assistant#Reverse Proxying with nginx|reverse-proxy]], which allows sharing ports 80/443 (http/https) and offers TLS termination.
 
If you don't plan on using a reverse-proxy, you can allow unencrypted access by opening up the port home-assistant is running on in your firewall. This is not generally recommended, since credentials will be transmitted in plain text and browsers tend to limit certain functionality (e.g. geolocation) to HTTPS.
 
<syntaxhighlight lang="nix">
{
  config,
  ...
}:


<syntaxHighlight lang=nix>
{
{
   networking.firewall.allowedTCPPorts = [ <other ports> 8123 ];
   networking.firewall.allowedTCPPorts = [
    config.services.home-assistant.config.http.server_port
  ];
}
}
</syntaxHighlight>
</syntaxhighlight>
 
===== First start =====


On your first start you may see multiple <code><nowiki>ModuleNotFoundError</nowiki></code> in Home Assistants journal log. These are dependencies required to set up devices Home Assistant already found on the network.
=== First start ===
On your first start you may see multiple <code><nowiki>ModuleNotFoundError</nowiki></code> in Home Assistants journal log. These are dependencies required to set up devices Home Assistant already discovered on the local network.


The appropriate component to load can be looked up in the <code><nowiki>component-packages.nix</nowiki></code> file, that gets auto-generated as part of the packaging process.
The appropriate component to load can be looked up in the <code>[https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix component-packages.nix]</code> file, that gets auto-generated as part of the packaging process.


For example, we can map the following error to
For example, we can map the following error to
Line 139: Line 152:
     [...]
     [...]
</syntaxHighlight>
</syntaxHighlight>
* https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix


==== Using components without YAML configuration ====
==== Using components without YAML configuration ====


When a component has no YAML configuration its dependencies can in theory be installed by mentioning the component name in <code><nowiki>services.home-assistant.config.wled = {};</nowiki></code>. This is deprecated, since Home Assistant will usually complain about the config having been migrated into the graphical user interface.
When a component offers no YAML configuration its dependencies could in theory be installed by mentioning its component name in <code><nowiki>services.home-assistant.config.wled = {};</nowiki></code>. This is deprecated, since Home Assistant will usually complain about the config having been migrated into the graphical user interface.


In recent versions of the home-assistant this use case has become more prominent and therefore received a more straightforward implementation, that also ensures that the component is still provided by Home Assistant.
In recent versions of the home-assistant this use case has become more prominent and therefore received a more straightforward implementation, that also ensures that the component is still provided by Home Assistant.
Line 156: Line 167:
</syntaxHighlight>
</syntaxHighlight>


==== Making additional python packages available ====
==== Provide additional Python packages to Home Assistant ====


We control the dependencies we pass into the Home Assistant python environment through module options that make the dependencies available, when their relative component was declaratively mentioned.
We control the dependencies we pass into the Home Assistant python environment through module options that make the dependencies available, when their relative component was declaratively mentioned.
Line 186: Line 197:


Custom components can be found under [https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=home-assistant-custom-lovelace-modules pkgs.home-assistant-custom-lovelace-modules].
Custom components can be found under [https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=home-assistant-custom-lovelace-modules pkgs.home-assistant-custom-lovelace-modules].
=== Reusing existing YAML configuration ===
The module also supports passing it an existing configuration, however that comes with certain drawbacks. For example we cannot automatically detect the components, that your configuration requires. In that scenario you will need to resolve dependencies manually using the packages <code>extraComponents</code> parameter. Also you will be unable to reuse configuration values between parts of your NixOS configuration. A barebones setup to get you started may look like this:
<syntaxHighlight lang=nix>
{
  services.home-assistant = {
    enable = true;
    # Pass the path to the directory where your configuration.yaml
    # resides, /var/lib/hass might be a good location.
    configDir = /var/lib/hass;
    # Override the package to handle dependency management manually
    package = (pkgs.home-assistant.override {
      # https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix
      extraComponents = [
        "default_config"
        "esphome"
        "met"
      ];
      extraPackages = ps: with ps; [
        # Are you using a database server for your recorder?
        # https://www.home-assistant.io/integrations/recorder/
        #mysqlclient
        #psycopg2
      ];
    })
  };
}
</syntaxHighlight>
You may find the following script helpful. It looks up missing dependencies from the <code>home-assistant.service</code> systemd unit journal: https://gist.github.com/AngryAnt/74c047a2b8438517c822ffdd9663aa57


= Tracking the latest release =  
= Tracking the latest release =  
Line 280: Line 259:


Home Assistant supports PostgreSQL as a database backend for, among other things, its logger and history components. It's a lot more scalable and typically provides faster response times than the SQLite database, that is used by default.
Home Assistant supports PostgreSQL as a database backend for, among other things, its logger and history components. It's a lot more scalable and typically provides faster response times than the SQLite database, that is used by default.
Remember to make backups of your database, for Home Assistant is becoming more and more stateful and has moved away from a completely declarative YAML configuration for new and core components.
Also note that when overriding the package you may want to disable install checks as they tend to take a long time to complete.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 438: Line 413:
         {
         {
           alias = "Name To Display in Automations List";
           alias = "Name To Display in Automations List";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "binary_sensor.someid1";
             entity_id = "binary_sensor.someid1";
             to = "off";
             to = "off";
             for = "00:10:00";
             for = "00:10:00";
           };
           };
           condition = {
           conditions = {
             condition = "state";
             condition = "state";
             entity_id = "binary_sensor.someid2";
             entity_id = "binary_sensor.someid2";
             state = "on";
             state = "on";
           };
           };
           action = {
           actions = {
             service = "light.turn_off";
             action = "light.turn_off";
             entity_id = "light.someid";
             entity_id = "light.someid";
           };
           };
Line 460: Line 435:
         {
         {
           alias = "Name in Automations GUI";
           alias = "Name in Automations GUI";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "binary_sensor.someid";
             entity_id = "binary_sensor.someid";
             to = "on";
             to = "on";
           };
           };
           condition = [
           conditions = [
             {
             {
               condition = "state";
               condition = "state";
Line 477: Line 452:
             }
             }
           ];
           ];
           action = [
           actions = [
             {
             {
               service = "notify.notify";
               action = "notify.notify";
               data = {
               data = {
                 message = "Some Notification";
                 message = "Some Notification";
Line 485: Line 460:
             }
             }
             {
             {
               service = "siren.turn_on";
               action = "siren.turn_on";
               entity_id = "siren.someid";
               entity_id = "siren.someid";
             }
             }
Line 497: Line 472:
         {
         {
           alias = "Some Name";
           alias = "Some Name";
           trigger = {
           triggers = {
             platform = "numeric_state";
             trigger = "numeric_state";
             entity_id = "sensor.batteries";
             entity_id = "sensor.batteries";
             below = "45";
             below = "45";
           };
           };
           action = {
           actions = {
             service = "notify.notify";
             action = "notify.notify";
             data = {
             data = {
               message = "Low Battery Detected";
               message = "Low Battery Detected";
Line 515: Line 490:
         {
         {
           alias = "Object Went Unknown";
           alias = "Object Went Unknown";
           trigger = {
           triggers = {
             platform = "state";
             trigger = "state";
             entity_id = "switch.someid";
             entity_id = "switch.someid";
             to = "unknown";
             to = "unknown";
             for = "00:5:00";
             for = "00:5:00";
           };
           };
           action = {
           actions = {
             service = "notify.notify";
             action = "notify.notify";
             data = {
             data = {
               message = "Object Went Offline";
               message = "Object Went Offline";
Line 535: Line 510:
         {
         {
           alias = "Do Something At Certain Time";
           alias = "Do Something At Certain Time";
           trigger = {
           triggers = {
             platform = "time";
             trigger = "time";
             at = "23:00:00";
             at = "23:00:00";
           };
           };
           action = {
           actions = {
             service = "climate.set_temperature";
             action = "climate.set_temperature";
             entity_id = "climate.thermostat";
             entity_id = "climate.thermostat";
             data = {
             data = {
Line 578: Line 553:
= Example configurations =
= Example configurations =


* [https://github.com/Mic92/dotfiles/tree/master/nixos/eve/modules/home-assistant Mic92's config]
* [https://github.com/Mic92/dotfiles/tree/393539385b0abfc3618e886cd0bf545ac24aeb67/machines/eve/modules/home-assistant Mic92's config]


= Misc =
= Misc =
Line 585: Line 560:


When developing Home Assistant for some test dependencies additional libraries are needed.
When developing Home Assistant for some test dependencies additional libraries are needed.
A nix-shell expression for this is available [https://github.com/nix-community/nix-environments here].
A nix-shell expression for this is available [https://github.com/nix-community/nix-environments/tree/master/envs/home-assistant here].


[[Category:Applications]]
[[Category:Applications]]
Retrieved from "https://wiki.nixos.org/wiki/Home_Assistant"