Philips Hue works with Home Assistant in two ways. You can use the Hue Bridge, which keeps Hue’s scenes and app features, or pair the bulbs directly over Zigbee with ZHA or Zigbee2MQTT and skip the bridge. If you already own a bridge, start with it.
Which way should you connect Hue?
| Hue Bridge | Direct Zigbee (ZHA or Zigbee2MQTT) | |
|---|---|---|
| Setup | Hue integration finds the bridge | Pair bulbs to your Zigbee coordinator |
| Hue scenes | Kept, and imported as scene entities | No dynamic Hue scenes out of the box |
| Extra hardware | The Hue Bridge | None beyond your coordinator |
| Button events | Yes, through the Hue integration | Yes, through Zigbee |
Hue bulbs use Zigbee, not Wi-Fi. Some models also support Bluetooth, which a separate Hue BLE integration can use.
Set up the Hue Bridge
- Set up your lights and bridge in the Hue app first.
- In Home Assistant, go to Settings > Devices & services. Under Discovered, select Philips Hue. If it isn’t listed, select Add integration and search for Philips Hue.
- When prompted, press the link button on top of the bridge, then submit within the time window. Pairing usually takes about 30 seconds.
- Give the bridge a DHCP reservation so its IP address doesn’t change.
You don’t need to sign in to a Hue account in Home Assistant. The integration talks to the bridge on your local network.
Bridge versions and limits
- Square (v2) bridge: uses the API v2 event stream, so Home Assistant gets updates as they happen.
- Round (v1) bridge: discontinued. It polls for updates, and support may be limited. Check before you reuse one.
- Limits: a v2 bridge handles roughly 50 lights and about a dozen sensors and switches. These limits are soft and vary by setup.
- Hue Bridge Pro: a newer model that’s designed to handle more lights, and the same integration works with it. Check its current specifications before you buy.
What you get in Home Assistant
- Lights: each bulb is a light entity. Rooms and zones show up as grouped light entities.
- Scenes: Hue scenes import as scene entities. The
hue.activate_sceneaction supports dynamic scenes, speed and brightness. - Motion sensors: each one adds motion, temperature and light-level entities, which you can use to turn on lights with a motion sensor.
- Dimmers and buttons: Hue Dimmer, Hue Smart Button and Tap Dial presses appear as event entities and device triggers.
- Hue Play HDMI Sync Box: has its own integration.
- Matter: the bridge can also act as a Matter bridge. The native Hue integration has more features, so use it unless you have a specific reason to use Matter.
Connect Hue bulbs without a bridge
You can pair Hue bulbs straight to a Zigbee coordinator that runs ZHA or Zigbee2MQTT:
- Set up ZHA or Zigbee2MQTT with a supported coordinator. See ZHA vs Zigbee2MQTT to choose.
- Reset each bulb, or remove it from an existing bridge first.
- Turn on pairing in ZHA or Zigbee2MQTT, then power on the bulb to join it.
The trade-offs are real. You lose the bridge’s built-in Hue scenes, and a bulb can’t be on the Hue bridge and on Home Assistant’s Zigbee network at the same time. You gain one less hub, and everything shares one Zigbee mesh. Community members report that direct Zigbee pairing is reliable and exposes button events from Hue switches.
Reset a Hue bulb
Use any of these methods to reset a bulb before you pair it again:
- The Hue app
- The Hue Bluetooth app, for Bluetooth bulbs
- Touchlink
- Holding On and Off on a Hue dimmer for about 10 seconds, while standing near the bulb
Troubleshooting
- If the bridge doesn’t show up, check that Home Assistant and the bridge are on the same network, then add a DHCP reservation for the bridge.
- If a bulb won’t join directly, reset it, turn on pairing again, and try once more.
For the general model of integrations, devices and entities, see adding and managing devices in Home Assistant. For a wider look at lighting choices, see smart lighting, switches and buttons.