WTF {% %} {{ }} Jinja2

This is probably more of a rant but, you asked:
This was my What The * (and still is) when working with Home Assistant

There is so much that is user friendly, preconfigured and works out of the box in HA (thanks to all the work of everybody who has contributed) and then I find myself writing “jinja2”

Who thinks coding where you you have to surround statements with {% %} {{}}
is a good idea?
Its sooo * and such a HUGE BARRIER to entry.
How many millions of hours have been wasted because of syntax errors or single character errors
Really who thought that jinja2 embedded in yaml was a good idea and human friendly?

Do I expect you to change it it - no, I suspect its too embedded now
but if you wonder why people look at HA, see the examples of integrations in yaml in jinja2 and then drift away and use a different platform this has to be one of the biggest barriers to adoption

It needs to invest some time to learn Jinja. Good news is that it is very popular and powerful templating language.

This is more of a usability complaint than a suggested improvement.

Do please feel free to open a forum topic to discuss this. There are many alternatives to using templates.

1 Like

Unfortunately, it’s not true that you just have to learn YAML and Jinja to create automations.
First of all, you have to know where you can and you can’t use templates.
For instance, you can do scene.create selecting entities with something like {{ states['light']|rejectattr('state','eq','unavailable')|map(attribute='entity_id')|join(',') }}, but you can’t do scene.apply to turn off all lights in “on” state in a similar way - and getting “dictionary error” doesn’t help to understand what’s wrong.
Then, Jinja is a sort of initiated-only magic. For instance, you can get an entity_id components with .split(".") method, but the Jinja documentation contains no mention about this method. You can filter entities by selectattr('attribute','match','[regex]'), but “match” is not described in standard filters. Still today I don’t understand where these stem from.

So, no, at least half of what you need to know has to be learned in hours of frustration, searching in forums or asking again and again the same questions.
When I installed HA and saw all my devices pop up on the dashboard I said “wow!”, but I think YAML+Jinja was an unfortunate design choice, the main weak point of HA.

However I understand it’s not easy to change this. Although partially, this can be dealt with by creating multiple “dumb” automations. However, some way to organize them is needed, and that’s why this is the top request in ‘Month of “What the heck?!”’


If you hate wasting time with syntax errors, go Node Red. You’ll end up writing a tiny fraction of code compared to YAML.

Sorry to say but removing jinja from HA will most likely never happen. The {{ }} and {% %} are staples in jinja code, the only way to remove this is to remove jinja. Replacing jinja would be a colossal change and would break most integrations. Not to mention, all mqtt devices that interface with home assistant would break. And the change for that break would have to occur on the sensors themselves, not in HA. Meaning all companies that use MQTT would need to update their sensors to get them working again with discovery in HA.

I suggest you move to other options if you don’t like Jinja. Like pyscript, appdaemon, nodered, etc.

1 Like

Yes, I’ve tried AppDaemon, pyscript, python_scripts and Node-Red.

  • python_scripts cannot have triggers, so you still have to rely on YAML+Jinja for these
  • Pyscript seems easy and coincise, but I found it way too unstable. After installing I got big fat warnings saying it could break HA. I dismissed them a bit worried, and I proceeded writing my first automation, made of 2 lines: a trigger on a device attribute (temperature of generic_thermostat) and a log message. I spent an hour trying to understand why it wouldn’t trigger, then I’ve tried to restart HA, and it began to work. So I added a third line, and it stopped triggering again. Not a good first look.
  • Node-Red: great interface, great debugging; but I’ve tried it two times, and immediately I found myself writing code inside nodes. If I have to do that, I can do it on a text editor (I guess this more because of how HA internals are exposed to it, not Node-Red itself).
  • I’m trying AppDaemon now, but callbacks and the plethora of “self.” doesn’t make it so friendly - but at least it’s poweful.

I think HA need something between YAML and AppDaemon. I understand removing Jinja would break HA, but it’s not impossible to empower something else at its side.
Thinking about difficulties encountered by new HA users (like me) I’d at least put on official documentation:

  • A better documentation on how Jinja relates with YAML
  • That mysterious Jinja “undocumented” methods and goodies (not the official documentation only)

Then, endorse one between Pyscript or Node-Red, or even AppDaemon, and make operations as smooth as possible, making it easy for casual users.

1 Like

Not sure what you’re referencing here. There’s the HA Jinja documents which cover what HA has added to the Jinja environment, and then there’s Jinjas documents (managed and depolyed by the people who make jinja) which covers all the base jinja stuff. There are no ‘un-documented’ goodies, if there is (that HA added to the env), then it should be added to the HA docs. I’m assuming you’ve glanced over the link to the Jinja Documentation inside the HA template documentation?

All of these are custom and managed by users outside HA. There’s a near zero chance of them getting endorsed as official, they will always remain in the custom universe unless the authors of those custom items want to add them to core. IIRC, appdaemon is built to run without HA and they have no desire to put it into HA. Pyscript would be a good candidate, but again up to the dev. Node-red is another automation engine that doesn’t need to run with HA, so that’s most likely out of the question as well.

you can get an entity_id components with .split(“.”) method, but the Jinja documentation contains no mention about this method. You can filter entities by selectattr('attribute','match','[regex]'), but “match” is not described in standard filters

I’m referring to these. If there’s a document about these, of couse my rant has no basis.

There are documents about them.

Templating - Home Assistant (

My guess here is that you’ve never looked at the selectattr documentation in the jinja docs to understand that the 2nd argument for selectattr is a test.

I suggest spending spending time to learn the differences between a filter, a function, and a test and where to use them

Sorry Petro, probably it’s me (although I’m not the only one); I’m referring to this Jinja documentation: Template Designer Documentation — Jinja Documentation (3.1.x). There’s no “match” under “List of builtin tests”; and there’s no “split” either. I read there’s a post about search and match tests, but how am I supposed to find it when I develop templates? These kind of information should be collected in a FAQ or something similar at least

Because ‘match’ is something HA added to HA’s version of Jinja, therefore it’s in the HA docs, not the jinja docs.

HA did not create Jinja. HA uses it, and extends its functionality. You have to use BOTH documentations to write jinja in HA.

As you can see in the document I listed, the match line literally says Test match..., indicating it’s a test.

split is a class function on strings, which is linked from the jinja documents.

This covers the section about python methods → Template Designer Documentation — Jinja Documentation (3.2.x) ( [EDIT]: So it’s not linked directly, however it mentions that a python objects methods are available for use, and .split is one of those methods that’s available on strings.

Keep in mind this is an API, so the documents are like any other api’s documents. Also keep in mind, that HA has no say in Jinja’s documents. Only HA’s documents.

Writing code in NR is just an option the vast majority of the times, not an imposition, and you can do the most complex flows without touching code. In my whole NR instance I only have one function node and I didn’t write it myself, The rest is pretty much absent of code. NR really is idiot proof.

My curse is that I always find things that cannot be done the easy way. :wink:
Last time I was trying to create a trigger based on an attribute change. I had to use JSONata as $entity().attributes.temperature > 19 just for trigger; but I figured out I needed more if I wanted to create a “general” automation.
I don’t remember what previous time’s goal was, but it ended up the same way. I know one variable isn’t “coding”, but what I mean is that 1) You have to dip into objects, methods, and so on 2) there’s no specific documentation, you have to find someone explaining it to you

There’s documents for all objects that are usable in templates, but you have to know where to look. If it’s a python object created by python, you have to look in pythons docs. If it’s an object created by HA, you have to look in HA docs and it’s typically linked from the HA template docs (like state objects, which is what you’re referencing).

trigger objects all have documents. Same with context objects. Only objects that don’t are event data that comes directly from devices. However you can get the object structure by listening to the event in the dev tools events page.

The majority of fields auto-complete. With the majority that don’t, you can just copy/paste paths. It is so silly proof my mom built a flow to turn a light on with a door sensor without my help and loved it, you don’t really need that much documentation. And there’s in fact documentation for every node in the right side menu. It’s really syntax error proof.

I appreciate you’re trying to give me help. However, I wouldn’t be so generic in asking, mine is simply a rant :slight_smile:
Here is how it goes: someone (like me) starts using HA; after simple ones, they desire some automations just beyond “click there>lamp on/off” - like each time a button is pressed, light in a group turn on in sequence, and when they’re all on the begin to turn off the same way. Having several light groups, a reusable automation would be perfect: just pass it a list of lights and it does all the rest.
They read “it’s easy, just read these docs, there’s autofill, even my mom could”. So it’s just a matter of defining some parameters and apply them at the right place; study Jinja syntax, find a good object reference and you’re ready.
After some late evenings of frustration, they conclude that’s not the case. It’s a full time work.

I’d prefer to be advised in advance: “stick to simple automation. There will be redundancy and you may need to revise several things if you just change an id, but it’s still easier than going full power. Otherwise begin here, but that’s not enough, be prepared to learn object programming models, concurrent processing, event-driven calls and so on. Templating can be a ‘lighter’ solution, but it’s not easy too.”

Maybe it’s me, I agree; but when I began working with computers, it was exciting that by following some naming convention, you could delete your old tax documentation by issuing “del 2001*.xls”, and you could remember that even one year to another and learn something different in the meantime. That’s the kind of simplicity I miss.

That’s quite an advanced automation no one should say this:

Simple automations are point and click.

What you described will require learning. Everyone has different abilities and for some this takes more effort than others. But there are plenty of knowledgeable users on this forum willing to help, for free.


Templating YAML with Jinja2 started as a big trend a few years back. It’s not only HA that did it, by far. A lot of other software (mostly open source though) jumped on that train to hell. Ansible, looking at you here… It’s like all the developers of XML/XSLT sat around a table and went Okay guys, we need a new config as code or vice versa mishmash format, but it needs to be even worse than what we have, it needs to be completely unreadable, undebuggable, needs tons of syntactic whitespace, oh and it needs to be turing complete ! Go !..

YAML as a pure config format is not great, but manageable with the right tools. Jinja2 is an abomination. Unfortunately, as petro mentioned, changing this now is next to impossible. It would break literally everything. Some mistakes will follow you forever.

1 Like