# Thermal Comfort turns a temperature and humidity pair into a feeling > thermal_comfort is a Home Assistant custom integration that computes a variety of thermal indices from a temperature and humidity reading, in numeric and textual form. It suits Home Assistant users who want automations driven by apparent temperature rather than raw sensor values, and it changed behaviour significantly at version 3. **dolezsa/thermal_comfort** — Thermal Comfort sensor for HA (absolute humidity, heat index, dew point, thermal perception) - Repository: https://github.com/dolezsa/thermal_comfort - Stars: 898 · Forks: 134 - Language: Python - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/dolezsa-thermal-comfort ## Two families of sensor, numeric and perceptual thermal_comfort is a Home Assistant custom integration that provides thermal indices and thermal perceptions, including feels-like temperatures in numeric and textual representation. The README splits the output into two kinds, and the split is the clearest way to understand what the integration gives you. The numeric indices are physical quantities. Dew point, frost point, absolute humidity and moist air enthalpy fall into this group, and they are values that can feed further automations while still being readable by a human. The README uses dew point as the illustration: it tells the temperature to which air must be cooled to produce dew on a surface. The perception indices are what a body would feel. The bio indices include humidex and heat index, which give numeric values of human perceived temperature, and alongside them the integration provides textual perception sensors that describe a range of an index in human-readable form, such as comfortable or uncomfortable. That combination is why the integration is more than a formula collection. A numeric index is what you branch on in an automation. The textual sensor is what you put on a dashboard, because a number like 32.4 does not tell a household anything on its own, while a word does. The repository also ships an icon pack, custom icons for the sensors, so the same information can be carried by the shape of the icon rather than only by the label. The full list of sensors is kept in a separate document, documentation/sensors.md, so the set of indices available is larger than what the README enumerates. ## Two ways to set it up, and the one that changed at 3.0 There are two configuration paths, and the README links to a document for each. One is the UI, described in the config flow documentation, and the other is YAML, described in the yaml documentation. Both are current, and both are the way to define a sensor. What the config flow document covers is the setup of a sensor through the frontend, and the yaml document covers the same thing in configuration file form. The README points at the yaml document specifically for the sensor configuration variables, which is where the custom icon options and the other per-sensor settings are described. The 3.0 release changed the option layout. The README notes that polling, the poll interval, custom icons and the enabled sensors are now in a collapsed Advanced options section, that advanced mode is no longer needed, and that existing entries keep working unchanged. That last clause is the reassuring part for an existing installation, and it is also the reason to read the notes before upgrading, because a config file that predates 3.0 will still load while the meaning of a few defaults has moved. One thing 3.0 did add is freedom in where the input comes from. Any sensor entity can be chosen as a temperature or humidity source, and sensors with a matching device class are listed first, which is what makes the integration usable with a wide range of hardware without a per-device configuration file. ## Installing it, and the version that matches your Home Assistant The requirement is stated plainly: Home Assistant 2025.8.0 or newer, which needs Python 3.13 or newer. Older installations are not stranded, because the 2.2 releases support Home Assistant 2023.12.0 or newer and the 1.5 releases cover even older versions, each with its own documentation branch. The recommended route is HACS. The README describes it as opening HACS, searching for Thermal Comfort, downloading it and restarting Home Assistant. The repository has a hacs.json at the top level, which is what makes the integration discoverable that way. The manual route is a git clone and a copy of the custom_components directory into the configuration folder: ```sh git clone https://github.com/dolezsa/thermal_comfort.git cd thermal_comfort # if you want a specific version checkout its tag # e.g. git checkout 1.0.0 # replace $hacs_config_folder with your home assistant config folder path cp -r custom_components $hacs_config_folder ``` The alternative manual route is to download thermal_comfort.zip from the latest release and extract it into the custom_components/thermal_comfort folder. Either way, the last step is the same: restart Home Assistant before using it. One detail to plan for is the icon pack. The README states that the icon pack is no longer available in the HACS default repositories, and that you need to follow the installation instructions in its own repository instead. It is a separate project, thermal_comfort_icons, and the custom icon options then have to be enabled per sensor in the frontend or in YAML. The repository tooling is worth noting if you plan to contribute. The pyproject configures pytest with the tests directory as the test path, asyncio in auto mode, and ruff targeting Python 3.13 with a broad rule selection including the bugbear, complexity, pylint, docstring, isort and logging-format families. ## The 3.0 upgrade changes what your automations will see The upgrading notes are the most important section of the documentation for anyone on 2.x, and they are specific enough to be worth reading line by line. The behavioural change that will break things is availability. In 2.x, a calculated sensor kept its last value when a source sensor was unavailable, unknown or out of range. In 3.0 the calculated sensors are unavailable in those situations instead, and they also start as unavailable rather than unknown until both sources are valid. An automation that treated a stale comfortable reading as current will now see the sensor go missing, which is arguably more correct and is definitely a change in behaviour. The notes tell you to adjust automations or templates that relied on the old behaviour. The second change is on the input side. Humidity readings up to 105 percent are now treated as 100 percent, which matters for sensors that occasionally report above 100 in a damp environment or after a calibration drift. The third is numerical. Corrected formulas change the values of two attributes: thoms_discomfort_index, typically about 0.4 to 1.1 degrees higher at 40 to 70 percent humidity and more at higher humidity, and, from 3.0.1 onwards, winter_scharlau_index. The state of the Thom's discomfort and winter Scharlau perception sensors changes with them, which means a dashboard that shows a text label may show a different word after the upgrade even though the underlying conditions are identical. The last change is about storage. The absolute humidity sensor has the absolute_humidity device class, and the temperature and humidity attributes are no longer stored in the recorder, so a query against the recorder for those attributes will return nothing. ## What it does not tell you The integration is a menu of published comfort formulas, and it is worth being clear that this is different from a comfort certification. The indices it computes, humidex and heat index among them, are standardised measures of apparent temperature, and a person can disagree with them in specific circumstances. The README describes the textual sensors as describing the range of an index, which is a careful phrasing that acknowledges the index is a range rather than a verdict. The larger limitation is what the input side cannot fix. Every index here is derived from one temperature reading and one humidity reading. There is no air speed, no clothing level, no radiant temperature from a wall or a window, and no metabolic rate. A person standing next to a cold window in a warm room and a person in the middle of the same room report different comfort, and the integration will report the same number for both. Any comfort model that accounts for those factors is outside what this integration does. There is also a question of what the humidity sensor is doing. The 3.0 notes make it explicit that the calculated sensors are unavailable when a source is out of range, so a sensor that drifts or drops out takes every derived index down with it. The integration does not smooth or impute; it propagates the unavailability, which is the right behaviour for an automation but means the quality of a comfort reading is the quality of your cheapest sensor. For the same reason, the integration is the wrong tool for a monitoring-only setup. If nobody branches on the value, the raw temperature and humidity entities already carry everything the index adds, and the extra entities are just noise in the recorder. ## MIT terms, a fast release line, and a translated interface The project is licensed under the MIT licence, with a LICENSE file at the repository root, and credits are listed in CREDITS.md. Bug reports and questions go to the issues tracker, and CONTRIBUTING.md covers contribution. The release history is unusually quick. The recent versions are 3.0.1 and 3.0.0 both on 2026-10-19, and before that 2.2.6 on 2026-02-22. The last push was on 2026-10-19 as well. A major version and its patch release landing on the same day, with a gap of eight months to the previous line, is the pattern of a maintainer landing a large rewrite rather than a steady drip of features. The 3.0 notes are long and specific, which fits that reading, and it is the reason to plan the upgrade rather than accept it. Localisation is handled through the inlang tooling, with a project.inlang.json and a project.inlang directory at the top level, an editor at Fink, and contributions requested either as pull requests or through that editor. The icon pack is a separate repository with its own installation flow, and the same split applies to the documentation, which lives in a documentation directory alongside the sensor list, the config flow guide and the yaml guide. Because the integration is a Home Assistant custom component rather than a core feature, the upgrade path is under the maintainer's control, not the platform's. That is the trade for the breadth of indices: a core integration would be reviewed and shipped with Home Assistant itself, while this one can iterate on its own schedule and break its own compatibility between versions, as 3.0 did. ## Conclusion thermal_comfort suits a Home Assistant user with a temperature and humidity sensor who wants automations keyed to how the room actually feels, and who is willing to check the 2.x to 3.0 behaviour changes before upgrading, because the calculated sensors now go unavailable rather than holding a stale value. It is the wrong tool for a monitoring-only setup, where a comfort index adds no information over the raw reading, and the wrong tool for anyone who needs a comfort model for a specific standard, since the project implements a menu of published indices rather than a certified rating. Before you adopt it, read the upgrading notes in the repository, because the 3.0 release changes unavailable behaviour, caps humidity readings at 100 percent and moves several options into a collapsed section, and confirm which sensor your platform reports, since the source of the humidity reading is what every index is derived from. ## FAQ ### What is the thermal_comfort Home Assistant integration? It is a custom integration that provides thermal indices and thermal perceptions, including feels-like temperatures in numeric and textual form. It includes numeric indices such as dew point, frost point, absolute humidity and moist air enthalpy, and perception indices such as humidex and heat index. ### How do I install thermal_comfort in Home Assistant? Through HACS, by searching for Thermal Comfort, downloading it and restarting Home Assistant, or manually by cloning the repository and copying the custom_components directory into your Home Assistant configuration folder. Home Assistant 2025.8.0 or newer with Python 3.13 or newer is required for version 3. ### What changed when thermal_comfort went to version 3.0? Calculated sensors now become unavailable when a source sensor is unavailable, unknown or out of range instead of keeping the last value, humidity readings up to 105 percent are treated as 100 percent, corrected formulas change the thoms_discomfort_index and winter_scharlau_index attributes, and options moved into a collapsed Advanced options section. ### Can thermal_comfort use any temperature and humidity sensor? Yes. Since version 3.0 any sensor entity can be chosen as a temperature or humidity source, and sensors with a matching device class are listed first in the configuration. ## Sources - [dolezsa/thermal_comfort on GitHub](https://github.com/dolezsa/thermal_comfort) - [Issues](https://github.com/dolezsa/thermal_comfort/issues) - [License: MIT](https://github.com/dolezsa/thermal_comfort/blob/master/LICENSE) - [README](https://github.com/dolezsa/thermal_comfort/blob/master/README.md) - [Releases](https://github.com/dolezsa/thermal_comfort/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dolezsa-thermal-comfort