Skip to main content
mattercatalog

How to add a Matter device to Home Assistant

Updated October 20, 2026 · Steps paraphrased from each platform's or maker's own help pages, linked beside each step. We have not tested these steps ourselves.

Short answer

How do I add a Matter device to Home Assistant?

Add the Matter integration in Home Assistant (Settings, then Devices & services), which installs the Matter Server app on Home Assistant OS. Then, in the Home Assistant Companion app on your phone, go to Settings, Connectivity, Matter, tap Add device, choose No. It’s new, and scan the device’s QR code.(Home Assistant: Matter)

Your phone needs Bluetooth on, and a Thread device needs a Thread border router on your network, such as a HomePod mini, an Apple TV 4K, a Nest Hub (2nd gen) or Home Assistant’s own OpenThread Border Router.(Home Assistant: Matter)

Prepare Home Assistant

  1. Update Home Assistant to the latest version.(Home Assistant: Matter)
  2. Go to Settings, then Devices & services, and add the Matter integration.(Home Assistant: Matter)
  3. When asked for the connection method on a regular Home Assistant OS setup, select Submit: this installs the official Matter Server app. If you already run a Matter server elsewhere, untick the box and give its URL.(Home Assistant: Matter)

Home Assistant OS is the only supported setup; in a container you can run the Matter server’s Docker image, at your own risk.(Home Assistant: Matter)

Add a new device with an iPhone

  1. Open the Home Assistant app and go to Settings, Connectivity, Matter.(Home Assistant: Matter)
  2. Tap Add device, then No. It’s new.(Home Assistant: Matter)
  3. Scan the QR code, or tap More options to type the setup code, then tap Add to Home Assistant. Setup can take a few minutes.(Home Assistant: Matter)
  4. If asked, give the device a name (only iOS uses it), tap Continue and Done, then choose a name and an area in Home Assistant and tap Finish.(Home Assistant: Matter)

Add a new device with an Android phone

  1. Power the device up. Most go into pairing mode on their own; others need it turned on as the maker’s instructions say.(Home Assistant: Matter)
  2. If your phone shows a pop-up, scan the QR code and choose Home Assistant when asked which app to use.(Home Assistant: Matter)
  3. No pop-up? In the app, go to Settings, Connectivity, Matter, tap Add device, then No. It’s new, and scan the code (or choose Setup without QR-code).(Home Assistant: Matter)
  4. When it finishes, tap Done, then name the device and choose an area.(Home Assistant: Matter)

Home Assistant asks Android users to set the Companion app’s Location permission to Allow all the time: otherwise Android can hide the Wi-Fi name from the app while it runs in the background, and setup can fail.(Home Assistant: Matter)

Add a device that is already in Apple Home or Google Home

  1. In the Companion app, go to Settings, Connectivity, Matter and tap Add device.(Home Assistant: Matter)
  2. Choose Yes. It’s already in use, pick the app the device is in (for example Google Home) and follow the steps.(Home Assistant: Matter)

The device then works from Home Assistant and from the other app.(Home Assistant: Matter)

See also: Use one Matter device with two apps

Thread devices

Home Assistant uses a Thread border router only to reach the Thread network: your devices do not have to be added to Apple’s or Google’s apps for that, and the border router cannot read the encrypted Matter traffic it passes along.(Home Assistant: Matter)

Border routers Home Assistant lists as working with it: HomePod (2nd generation), HomePod mini and the Apple TV 4K models it names; Nest Hub (2nd gen), Nest Hub Max, Nest Wifi Pro, Nest Wifi and Google TV Streamer (4K); or Home Assistant itself, with the Thread radio of a Connect ZBT-1, Connect ZBT-2 or Yellow running the OpenThread Border Router app.(Home Assistant: Thread)

With Home Assistant as your border router, send its Thread network credentials to your phone from the Companion app before you add Thread devices.(Home Assistant: Thread)

See also: Thread network problems · Which devices are Thread border routers

Share, remove or update a device

To share a device with another app, go to Settings, Connectivity, Matter, Devices, select it and tap Share device, then scan or type the code in the other app. You do not need to press a button on the device.(Home Assistant: Matter)

To take one app’s access away, use Manage fabrics in the same place; Delete removes the device from Home Assistant.(Home Assistant: Matter)

Home Assistant shows an update entity for each Matter device that supports Matter’s over-the-air updates; not every device does.(Home Assistant: Matter)

See also: How to remove (unpair) a Matter device · How to update Matter firmware

If it fails

“You need to use the Home Assistant Companion app”: Home Assistant is open in a browser. Adding a new Matter device works only from the Companion app.(Home Assistant: Matter)

“Matter is currently unavailable” on Android: the Matter modules may not have downloaded yet. Home Assistant suggests waiting up to 24 hours for Google Play services, checking the phone meets the requirements, and reinstalling the Companion app or the Google Home app.(Home Assistant: Matter)

A Thread device will not pair: keep it in pairing mode, restart your phone, and check that mesh Wi-Fi is not filtering multicast traffic.(Home Assistant: Thread)

See also: Matter device won’t pair: what to check · Matter Wi-Fi requirements (2.4 GHz, IPv6)

Frequently asked questions

Does Home Assistant support Matter?

Yes. Home Assistant runs its own Matter controller as the Matter Server app, supported on Home Assistant OS, and adds devices through the Companion app on your phone.

Do I need a Thread border router for Matter in Home Assistant?

Only for Matter devices that use Thread. Home Assistant can use the Apple or Google border routers it lists, or act as one itself with a Thread radio such as the Connect ZBT-2.

Can I add a Matter device to Home Assistant from a computer?

No. Home Assistant says adding a new Matter device works only from the Companion app on a phone, which uses the phone’s Bluetooth during setup; the browser shows a message telling you to use the app.

Can a device be in Home Assistant and Apple Home at the same time?

Yes. Add it to Home Assistant with Yes. It’s already in use, or share it from Home Assistant with Share device and add the code in the Home app.

Sources

The steps above are written in our own words from these pages. Menus and wording in the apps can change; when they differ, follow the app and the page linked here.