Home Assistant Blueprints

What Are Blueprints?

A blueprint is a script, automation, or template entity configuration with certain parts marked as configurable. This allows you to create different scripts, automations, or template entities based on the same blueprint.^[1]

At their core, blueprints are YAML-based templates that encapsulate the logic of an automation. YAML, or "Yet Another Markup Language," is a human-readable data format used in Home Assistant to define configurations. They allow you to define general behavior while leaving specific details configurable.^[1]

Think of a blueprint like a cookie-cutter: the shape is fixed, but you get to choose the dough. An interesting use-case is described in the official documentation: imagine a blueprint that controls a light based on motion — it is now possible to create two automations that each have their own configuration for this blueprint and that act completely independently.^[4]

The Anatomy of a Blueprint

Blueprint schemas support three types of schema depending on their domain. The configuration schema consists of two parts: the blueprint's high-level metadata (name, domain, and optionally any input required from the user) and the schema for the blueprint domain it describes.^[2]

Configurable parts in blueprints are called inputs. To make an entity configurable, you replace the entity ID with a custom YAML tag !input.^[3] Inputs can be of any type — string, boolean, list, or map — and they can have a default value and provide a selector that ensures a matching input field in the user interface.^[2]

Why Blueprints Matter

One of the major advantages of Blueprints is their ability to be customized by any user, adapting to their needs, directly from the UI, without ever writing a single YAML line.^[4] This is a game-changer for the platform's accessibility.

1. Lowering the Barrier to Entry

The ultimate goal of projects like Awesome HA Blueprints is to develop a highly valuable resource for Home Assistant newcomers who would like to include complex automations in their home automation setups with just a few clicks, without even touching a single line of code.^[4]

2. Reusability & Consistency

Each automation created from a blueprint has its own configuration and acts completely independently, yet they share some basic automation configuration so that you do not have to set this up every time.^[1]

3. Automatic Propagation of Updates

Automations inherit from blueprints, which means that changes made to a blueprint will be reflected in all automations based on that blueprint the next time the automations are reloaded. This occurs as part of Home Assistant starting.^[1]

How Blueprints Work

Importing a Blueprint

Home Assistant can import blueprints from the Home Assistant forums, GitHub, and GitHub gists.^[1] The process is straightforward:

1. Go to Settings > Automations & scenes > Blueprints. Select the blue Import Blueprint button in the bottom right. A new dialog will pop up asking you for the URL. Enter the URL and select Preview.^[1]
2. This will load the blueprint and show a preview in the import dialog. You can change the name and finish the import. The blueprint can now be used for creating automations.^[1]

Creating an Automation from a Blueprint

To create your first automation based on a blueprint, go to Settings > Automations & scenes > Blueprints. Find the blueprint that you want to use and select Create automation. This opens the automation editor with the blueprint selected. Give it a name and configure the blueprint. Select the blue Save automation button in the bottom right corner.^[1]

"Taking Control" of a Blueprint

You can tweak an imported blueprint by "taking control" of this blueprint. Home Assistant then converts the blueprint automation into a regular automation, allowing you to make any tweak without having to fully re-invent the wheel.^[1]

Selectors: Making Inputs User-Friendly

Selectors describe a type and can be used to help the user pick a matching value. The selector for the motion sensor entity should describe that you want entities from the binary sensor domain that have the device class motion. The selector for the target light should describe that you want to target light entities.^[3]

Popular Blueprints

The Home Assistant Community Forum hosts a dedicated Blueprints Exchange section where blueprints are reusable automations and scripts that can easily be shared.^[1] Some standout blueprints include:

• Motion-Activated Lights — The built-in example and many community variants. The motion-activated lights blueprint by iainsmacleod uses motion sensors to confirm presence before activating or deactivating lighting, and can even be configured to control lights in accordance with the position of the sun.^[6]
• Frigate Notifications — The Frigate notifications blueprint by SgtBatten lets NVR setups send alerts to Home Assistant devices should cameras pick up anything out of the ordinary, with plenty of settings to tweak the notifications.^[6]
• Low Battery Level Detection — One of the most popular community blueprints that scans all battery sensors and notifies you when any device drops below a threshold.
• Wake-Up Light Alarm with Sunrise Effect — A sophisticated blueprint that creates a gradual brightness and color temperature sunrise effect for a natural alarm experience.
• Blacky's Sensor Light — One of the most common automations people use Home Assistant for is lighting. Blacky's community blueprints do more with light automation than many thought possible.^[6]

Evolution & Recent Changes

With the Home Assistant 2020.12 Release, the Blueprints feature was introduced.^[4] Since then, the system has matured significantly:

Key Milestones

• 2020.12 — Blueprints launched, initially only supporting the automation domain.
• Script support — While early tutorials focus on automation blueprints, scripts also support blueprints in the same way.^[3]
• Template entity support — Blueprint schemas now support three types of schema depending on their domain: automation, script, and template.^[2]
• Input Sections (2024.6) — Input sections are a new feature in version 2024.6.0. Authors must set the min_version for the blueprint to at least this version if using input sections.^[2]
• Advanced Selectors — Input fields for a Blueprint are now much smarter. They can filter entities by integration, by device model, or even allow for multiple selections.^[5]
• Version Control — Blueprint authors can now manage versions, meaning users can get update notifications and decide whether to apply changes, preventing an update from unexpectedly breaking existing automations.^[5]

Community & Ecosystem

The blueprint ecosystem thrives on community sharing. Blueprints are shared by the community in the blueprint community forum.^[1]

Curated Collections

Awesome HA Blueprints is a curated list of automation blueprints for Home Assistant, which can then be easily imported and updated in any Home Assistant instance. These blueprints are highly customizable and flexible to user needs, but still hide the complexity of their internal working.^[4] They are fully maintained, collaboratively developed and tested by the community.^[4]

Notable Contributors

Individual contributors like SirGoodenough have created and shared Blueprint libraries with both Script and Automation Blueprints in separate folders, each with thorough documentation.^[1] Blacky is a prolific Home Assistant blueprint author who frequently updates blueprints based on user feedback and new features.^[6]

Sharing Your Own

The final step in creating a blueprint is to share it with others. For tutorials, sharing via GitHub Gists is a good option if you don't want to publish to a larger audience.^[3] You can also share your blueprint on the Home Assistant Blueprint Exchange forum, which is accessible to the general Home Assistant community but recommended only for your original blueprints.^[3]

Challenges & Open Questions

Discoverability

The whole blueprint discovery experience is very "developer UX." It should be a first-party solution and not a bolt-on of the forums. Community members have long requested an integrated marketplace. The old forum category has evolved — now directly from the Home Assistant UI (via HACS and increasingly in Core), users can search, browse, and filter community Blueprints, with ratings and popularity metrics emerging.^[5]

Creation Complexity

Some users find creating blueprints difficult, reporting that they often seem to work until used in an automation, then fail with unhelpful error messages. This has been flagged in the community's "What the Heck?!" feedback events.

Single-Entity Limitation

Currently a blueprint is limited to only one automation, script, or template entity. However, sometimes you want to create multiple entities to work together — for example, one main script and one supporting script to be used in repeat loops. This is an active feature request on the architecture discussion board.

Breaking Changes on Update

Blueprints created by the community may go through multiple revisions. The quickest way to get changes is by re-importing the blueprint, which will overwrite the current blueprint. However, if the re-imported blueprint is not compatible, it can break your automations.^[1]

Performance Considerations

Some complex blueprints contain thousands of lines of interpreted code, which raises performance concerns when running many instances, especially on smaller hardware like a Raspberry Pi 5. Users with many motion zones should be mindful of blueprint complexity.

Where It's Headed

The future of Blueprints is tightly woven into Home Assistant's 2025 roadmap and beyond.

Device Database & Contextual Intelligence

Home Assistant is building on what contributors already share in integrations — knowledge about how devices are structured and how they should behave. The hope is that this will provide the framework for contributors to contribute dashboards and automation blueprints in exciting new ways.^[7]

The Device Database — a brand new project from the Open Home Foundation — is conceived as a source of truth created, curated, and validated by the community, gathering everything from metadata to real-world setup insights and community creations such as automation examples.^[7]

Human-Friendly Automations

Home Assistant is continuing work on "human-friendly" triggers, which can be enabled via Home Assistant Labs, so users can build automations using easy-to-understand language instead of technical state changes.^[8] This direction will make blueprint inputs even more accessible.

Template Blueprints in the UI

There are plans to bring template blueprints to the GUI, but many other changes are needed before this can happen. This will open blueprints to an entirely new category of reusable sensor and entity configurations.