Type “Xiaomi” into Home Assistant’s Add Integration search box and one of the results is labeled “Xiaomi Home.” That one is xiaomi_miio, the integration that has lived in HA core for years. Install Xiaomi’s own official integration through HACS, and a second entry appears under that identical name. If you followed an older guide that said to add xiaomi_miio, meanwhile, you can search for that exact string and never find it, because the picker doesn’t show domains at all. It shows “Xiaomi Home” both times.
This isn’t a rebrand you missed or a UI bug. It’s two genuinely different Home Assistant integrations, built by different maintainers, with different account requirements and different device coverage, that happen to share the exact same display name. I pulled up both projects’ own source files to confirm it. There’s a third option worth knowing about too, and it doesn’t appear under “Xiaomi Home” at all. This piece is the decision layer above all three: which one you actually want, and why the collision happened.
The three real options
Legacy xiaomi_miio is the integration that’s lived in Home Assistant core for years. It’s token-based: once you have a device’s local API token, commonly pulled with the Xiaomi Cloud Tokens Extractor tool, it talks to the device directly over your LAN using the miIO protocol. No ongoing Xiaomi account or cloud dependency after that token is in hand. It covers a defined, sometimes-frozen list of device categories: vacuums, fans, air purifiers, humidifiers, some Wi-Fi plugs and power strips, and Wi-Fi curtain controllers. It works because it speaks Xiaomi’s unofficial, reverse-engineered API, and that’s also its weak point: Xiaomi can change device-side behavior without notice and the integration can break silently when that happens.
The official xiaomi_home (GitHub project ha_xiaomi_home, written by Xiaomi itself) is newer and a separate codebase. Despite being first-party, it is not part of Home Assistant core: you install it through HACS, or by copying custom_components/xiaomi_home into your config directory by hand, and only then does it appear in the Add Integration list. Setup requires an OAuth 2.0 login to a Xiaomi account, available across six regional servers: mainland China, Germany, India, Russia, Singapore, and the US. It documents support for “most categories” of Xiaomi smart device, with Bluetooth, infrared, and virtual devices explicitly excluded.
The community hass-xiaomi-miot (sometimes called “MIoT Auto” in community discussion) also installs via HACS, but it appears under its own name in the integration picker, not “Xiaomi Home,” so it never joins the naming collision. It uses the newer MIoT-spec protocol rather than legacy miIO, and it’s the only one of the three that explicitly supports Wi-Fi, Bluetooth LE, and Zigbee Xiaomi devices through a single integration. It’s also the most flexible of the three on account requirements: add a device directly by local IP and token with no cloud account, or sign in with a Xiaomi account for discovery and pick a connection mode. Since v0.4.4 those modes are Automatic (local when supported, cloud fallback otherwise), Local (forces LAN for every device), and Cloud.
The display name won’t tell you which integration you already have installed. The config domain will: xiaomi_miio is the legacy integration, xiaomi_home is the official one. If you’re not sure which is running your devices right now, that domain string is the thing to check, not the “Xiaomi Home” label on the card.
Why they’re both called “Xiaomi Home”
This is the part that’s genuinely verifiable, not a guess. Home Assistant core’s legacy integration sets its own display name in code. Its manifest.json file, in the xiaomi_miio component directory, literally sets the name field to “Xiaomi Home.” Its documentation page carries the same title.
{
"domain": "xiaomi_miio",
"name": "Xiaomi Home"
}
The newer, separate project isn’t hiding the overlap either, it just doesn’t know it exists. ha_xiaomi_home‘s own README titles itself “Xiaomi Home Integration,” and its install steps tell you to search that same string in the Add Integration box. Neither project’s documentation mentions the other. There’s no note in either README saying “if you’re looking for the older/community one, see here.” I checked both repositories directly for exactly that kind of disclaimer and found nothing.
No official disambiguation page exists from either project or from Home Assistant itself.
I think shipping a first-party integration under the exact same display name as a project that’s already lived in HA core for years is a self-inflicted support burden Xiaomi didn’t need to create.
If you already have a working xiaomi_miio setup and you add the official Xiaomi Home integration because the search results made it look like an update, you now have two separate integrations that may both be trying to represent overlapping devices, under different entity IDs. Check the official integration’s supported-category list against your actual devices before you touch the working one. Don’t remove xiaomi_miio assuming the new option is a drop-in replacement.
Decision framework: which one actually fits
| Integration | Account required | Local path | Device coverage |
|---|---|---|---|
Legacy xiaomi_miio (HA core) |
No, once you have a local token | Direct LAN via miIO, using the device’s local token | Defined list: vacuums, fans, air purifiers, humidifiers, some Wi-Fi plugs/power strips, Wi-Fi curtain controllers |
Official xiaomi_home (ha_xiaomi_home, HACS) |
Yes, Xiaomi account via OAuth 2.0 | Only fully local with a Central Hub Gateway (China-only hardware); LAN control fallback exists but is more limited and Wi-Fi/Ethernet only | “Most categories” except Bluetooth, infrared, virtual devices |
Community hass-xiaomi-miot / MIoT Auto (HACS) |
No; add by IP and local token, or by account | MIoT-spec over LAN; local-only via direct IP+token setup, or Local mode (v0.4.4+) under account setup | Widest of the three: Wi-Fi, Bluetooth LE, and Zigbee Xiaomi devices in one integration |
If your devices are already on the legacy list and you want them fully off Xiaomi’s cloud once set up, xiaomi_miio is still the direct answer. If you need broader device coverage than that list and you’re fine with an account, the official integration is the one to pick, with the local-mode caveat below. If you’re chasing a device type neither one supports, especially anything Bluetooth or Zigbee, hass-xiaomi-miot is the option that comes up in community threads for that specific gap.
If you already have a working legacy setup, should you migrate?
No, not by default. xiaomi_miio‘s local-token path is the simplest of the three in terms of ongoing dependencies: once the token is pulled, there’s no account to log into and no cloud round-trip for control. For most readers outside China, migrating away from a working xiaomi_miio setup means moving from “local by default” to “cloud by default with a narrower local fallback,” which is the wrong direction unless a specific device or account requirement forces the move.
A concrete example already on this site: the Smartmi Humidifier 2 runs through exactly this legacy miIO path, local token and all, with no ongoing account tie. That’s the pattern worth keeping if it’s already working for you.
Worth knowing: Xiaomi vacuums have a separate local-control path outside all three integrations above, via Valetudo, which replaces the vacuum’s own cloud-connected firmware instead of talking to it through any of these HA integrations. It needs root access and a one-way flash, a much bigger commitment than any option above; we cover it separately.
What “local” actually means if you pick the official integration
The official integration’s local mode isn’t automatic. True local control needs that Central Hub Gateway (firmware ≥3.3.0_0023) or another Xiaomi device with a built-in hub, and the gateway hardware itself isn’t sold outside mainland China. A separate LAN-control fallback exists, but it only reaches Wi-Fi and Ethernet IP devices, not Zigbee or Bluetooth Mesh. The full breakdown, including what data crosses the cloud link by default, is in our deep dive on what “local” actually means in the official integration, and our companion piece on what data the Xiaomi Home integration actually sends.
A separate question is where your automations actually execute once devices are connected, cloud-side or on your own Home Assistant instance. We cover that in our Mi Home local execution versus cloud execution piece.
FAQ
Why does Home Assistant show two different “Xiaomi Home” integrations?
Because two separate projects both set their own display name to “Xiaomi Home” in their own source files. The legacy HA-core integration’s manifest.json sets "name": "Xiaomi Home" under domain xiaomi_miio. The newer, official XiaoMi-authored project, domain xiaomi_home, titles its own README “Xiaomi Home Integration.” Neither project’s documentation acknowledges the other.
Is xiaomi_miio the same as the official Xiaomi Home integration?
No. They’re different codebases from different maintainers. xiaomi_miio is the older HA-core integration, token-based and local-only once set up. The official xiaomi_home (ha_xiaomi_home) is a separate, newer project from Xiaomi requiring an OAuth account login. The config domain is the reliable way to tell them apart.
Do I need a Xiaomi account to use my Xiaomi Wi-Fi devices in Home Assistant?
Not necessarily. The legacy xiaomi_miio integration works from a device’s local API token with no ongoing account dependency. The official xiaomi_home integration does require a Xiaomi account via OAuth. The community hass-xiaomi-miot sits in between: add by local IP and token with no account, or use an account and force Local mode. Which one you need depends on whether your specific device is on the legacy integration’s supported list.
Which Xiaomi integration should I use: Miio, official Xiaomi Home, or MIoT Auto?
If your device is on xiaomi_miio‘s supported list and you want no account dependency, use that. If you need broader device coverage and can accept an account, use the official integration, keeping in mind its local mode is conditional on China-only hardware. If you need Bluetooth LE or Zigbee Xiaomi devices specifically, hass-xiaomi-miot is the community option that covers them.
Will the legacy xiaomi_miio integration keep working?
Yes — the integration isn’t deprecated or scheduled for removal, and ships in HA core today with a current docs entry. Specific legacy mechanisms inside it are on their own deprecation clocks, though: the battery_level attribute stops working in Home Assistant 2026.8 (replaced by a proper battery sensor), and the legacy, non-config-entry device tracker platform started a 12-month deprecation clock with the 2026.5 release, targeting removal in May 2027. Neither affects the core vacuum, fan, humidifier, or plug control most readers rely on. It still relies on Xiaomi’s unofficial API, so it can break silently on its own timeline, independent of these deprecations.
What this confirms, and what to check on your own setup
Confirmed directly from each project’s own repository files: the legacy xiaomi_miio integration’s manifest sets its display name to “Xiaomi Home” under domain xiaomi_miio. The separate, official ha_xiaomi_home project, domain xiaomi_home, titles its own README “Xiaomi Home Integration,” and its own install instructions tell you to search that same name in the Add Integration box. The community hass-xiaomi-miot project documents MIoT-spec protocol support spanning Wi-Fi, Bluetooth LE, and Zigbee Xiaomi devices via HACS.
What stays local: the legacy xiaomi_miio integration’s LAN/token path, once a device’s local token is in hand. What still depends on a vendor either way: Xiaomi’s own undocumented miIO API on the legacy path, or Xiaomi’s cloud account and, for full local mode, region-locked hardware on the official path. What to check on your own instance: open each “Xiaomi Home” entry under Settings, Devices & Services, and confirm which config domain it’s actually running, since the card label alone won’t tell you.
This is research-synthesis, not a bench test. No device was paired or reconfigured to produce this comparison. The facts above come directly from each project’s own manifest, README, and documentation pages, not from hands-on testing.