Technical Guide

Home Assistant Integrations: How to Find, Install and Troubleshoot Them

Last updated: 2026-10-17 · 7 min

Home Assistant & Zigbee: smart lighting controlled through HA integrations

A Home Assistant integration is the module that connects HA to a device, service, or platform and adds entities—sensors, switches, lights—to your setup.

Three types exist: official integrations (bundled with Home Assistant), HACS integrations (community-maintained), and manual custom integrations (dropped directly into your config folder).

Most mainstream devices have an official integration. If yours doesn't show up in the built-in list, HACS is almost certainly the next step. On a larger Zigbee network, the integrations layer is where most real-world problems surface.

Official vs HACS vs Manual: Which Type Is Your Integration?

Home Assistant ships with hundreds of official integrations maintained by Nabu Casa. HACS integrations are community-maintained and live outside the official release cycle. Manual integrations require direct file management.

Install pathMaintained byAuto-updatesNeeds extra software
Official (built-in)Nabu Casa + core teamYes, with HA updatesNo
HACSCommunity (GitHub)Via HACS update checkYes — HACS itself
Manual customCommunity (GitHub)NoNo

How to Add an Official Integration Through the HA Interface

The full path from nothing to a working integration takes five steps:

  1. 01
    Go to Settings → Devices & Services.
  2. 02
    Click Add Integration (bottom-right corner).
  3. 03
    Search by device brand, product name, or protocol (e.g., Philips Hue, MQTT, Zigbee Home Automation).
  4. 04
    Follow the configuration wizard—most ask for an IP address, API key, or OAuth login.
  5. 05
    Confirm that devices and entities are listed in the integration card.
Zigbee Hardware Note

Zigbee devices require a coordinator. You can choose ZHA (built-in) or Zigbee2MQTT. Zigbee2MQTT is one option for more granular control. Check our Zigbee coordinator guide or our Home Assistant Connect ZBT-2 review for hardware advice.

Installing Custom Integrations via HACS

HACS (Home Assistant Community Store) provides a searchable front-end for thousands of community integrations.

The Install Path

  • Open HACS from the sidebar and select Integrations.
  • Search for the integration and click Download.
  • Restart Home Assistant—this is required.
  • Add via Settings → Devices & Services.

HACS shows a badge count when updates are available. It is worth checking HACS after every major Home Assistant release to ensure compatibility.

Manual Install: No HACS Required

Some niche integrations are only available as direct GitHub downloads.

1

Download the .zip from the project's GitHub releases.

2

Copy folder to /config/custom_components/[name]/.

3

Restart Home Assistant.

Note: Staying on an old version is the most common cause of breakage after a HA update.

Troubleshooting Checklist

Connection Failures

Verify IP addresses haven't changed and check firewall rules on your router or VLAN boundaries.

Authentication Errors

Regenerate tokens and check that HA's system clock is accurate to avoid OAuth timestamp rejection.

Missing Entities

Check for 'disabled' entities in the device settings or check logs for connection timeouts.

Version Issues

Check HACS for update badges or look for GitHub issues if an integration breaks after a HA update.

Checking Version Compatibility

Every HACS integration lists a minimum supported HA version in its hacs.json file. Updating HACS integrations before updating Home Assistant reduces conflicts.

If things break, filter your logs to ERROR and look for custom_components to identify the culprit.

Want to expand your smart home even further?

Explore our deep dives into Zigbee, Z-Wave, and advanced automation strategies.

Browse all guides

Frequently Asked Questions

What is the difference between an integration and an add-on?

Integrations add entities (sensors/switches) to HA. Add-ons are separate software processes (like VPNs) that run alongside HA.

Can I run ZHA and Zigbee2MQTT at the same time?

No. A single coordinator can only be claimed by one. Use our coordinator migration checklist to switch.

How do I know if an integration is official?

If it appears in the 'Add Integration' search without HACS, it's official.

Do I always need to restart?

HACS and manual installs always require a restart. Many official ones do not, but it's the safest approach.

Why are some entities disabled by default?

HA hides less-used entities (like battery signal) to keep dashboards clean. You can enable them in the device settings.

Related Guides

Our pickZigbee Coordinator

Best Zigbee Coordinator for Home Assistant (2026)

Our pick for the most stable hardware recommendation.

Full walkthroughSmart Lighting

The Open-Source Path to Smart Lighting

A full project guide for HA and Zigbee lighting.

Protocol comparisonZigbee vs Z-Wave

Zigbee vs Z-Wave: 2026 Protocol Comparison

Which protocol should you choose for your home?