The HomeKit component allows you to forward entities from Home Assistant to Apple HomeKit, so they can be controlled from Apple’s Home app and Siri. Please make sure that you have read the considerations listed below to save you some trouble later. However if you do encounter issues, checkout the troubleshooting section.

It might be necessary to install an additional package: $ sudo apt-get install libavahi-compat-libdnssd-dev

# Example configuration.yaml entry configuring HomeKit
      - alarm_control_panel
      - light
      - media_player
      code: 1234
      name: Kitchen Table Light
      code: 1234
        - feature: on_off
        - feature: play_pause
        - feature: play_stop
        - feature: toggle_mute
      type: outlet

Configuration Variables


(map)(Required)HomeKit configuration.


(boolean)(Optional)Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. (Disable Auto Start)

Default value: true


(integer)(Optional)Port for the HomeKit extension.

Default value: 51827


(string)(Optional)Need to be individual for each instance of Home Assistant using the component on the same local network. Between 3 and 25 characters. Alphanumeric and spaces allowed.

Default value: Home Assistant Bridge


(string)(Optional)The local network IP address. Only necessary if the default from Home Assistant does not work.


(map)(Optional)Filters for entities to be included / excluded from HomeKit. (Configure Filter)


(list)(Optional)Domains to be included.


(list)(Optional)Entities to be included.


(list)(Optional)Domains to be excluded.


(list)(Optional)Entities to be excluded.


(map)(Optional)Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g., alarm_control_panel.alarm.


(map)(Optional)Additional options for specific entities.


(string)(Optional)Name of entity to show in HomeKit. HomeKit will cache the name on the first run so a device must be removed and then re-added for any change to take effect.


(string)(Optional)Code to arm / disarm an alarm or lock / unlock a lock. Only applicable for alarm_control_panel or lock entities.

Default value: <No code>


(list)(Optional)Only for media_player entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema.


(string)(Required)Name of the feature to add to the entity representation. Valid features are on_off, play_pause, play_stop and toogle_mute. The media_player entity must support the feature to be valid.


(string)(Optional)Only for switch entities. Type of accessory to be created within HomeKit. Valid types are faucet, outlet, shower, sprinkler, switch and valve. HomeKit will cache the type on the first run so a device must be removed and then re-added for any change to take effect.

Default value: switch


To enable the HomeKit component in Home Assistant, add the following to your configuration file:

# Example for HomeKit setup

After Home Assistant has started, the entities specified by the filter are exposed to HomeKit if they are supported. To add them:

  1. Open the Home Assistant frontend. A new card will display the pin code.
  2. Open the Home app.
  3. Click Add Accessory, than select Don't Have a Code or Can't Scan? and choose the Home Assistant Bridge.
  4. Confirm that you are adding an Uncertified Accessory by clicking on Add Anyway.
  5. Enter the PIN code.
  6. Follow the setup be clicking on Next and lastly Done in the top right hand corner.
  7. The Home Assistant Bridge and the Accessories should now be listed in the Home app.

After the setup is completed you should be able to control your Home Assistant components through Home and Siri.


Accessory ID

Currently this component uses the entity_id to generate a unique accessory id (aid) for HomeKit. The aid is used to identify a device and save all configurations made for it. This however means that if you decide to change an entity_id all configurations for this accessory made in the Home app will be lost.

Device Limit

The HomeKit guidelines only allow a maximum of 100 unique accessories (aid) per bridge. Be mindful of this when configuring the filter(s).

Persistence Storage

Unfortunately HomeKit doesn’t support any kind of persistent storage - only the configuration for accessories that are added to the Home Assistant Bridge are kept. To avoid problems it is recommended to use an automation to always start HomeKit with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)

A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable auto start and turn off the Start HomeKit automation (if you have one).

Disable Auto Start

Depending on your individual setup, it might be necessary to disable Auto Start for all accessories to be available for HomeKit. Only those entities that are fully setup when the HomeKit component is started, can be added. To start HomeKit when auto_start: False, you can call the service homekit.start.

If you have Z-Wave entities you want exposed to HomeKit then you’ll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won’t be fully set up until then. This can be automated using an automation:

# Example for Z-Wave
  auto_start: False

  - alias: 'Start HomeKit'
      - platform: event
        event_type: zwave.network_ready
      - platform: event
        event_type: zwave.network_complete
      - platform: event
        event_type: zwave.network_complete_some_dead
      - service: homekit.start

For a general delay where your component doesn’t generate an event, you can also do:

# Example using a delay after start of Home Assistant
  auto_start: False

  - alias: 'Start HomeKit'
      - platform: homeassistant
        event: start
      - delay: 00:05  # Waits 5 minutes
      - service: homekit.start

Configure Filter

By default no entity will be excluded. To limit which entities are being exposed to HomeKit, you can use the filter parameter. Keep in mind only supported components can be added.

# Example filter to include specified domains and exclude specified entities
      - alarm_control_panel
      - light
      - light.kitchen_light

Filters are applied as follows:

  1. No includes or excludes - pass all entities
  2. Includes, no excludes - only include specified entities
  3. Excludes, no includes - only exclude specified entities
  4. Both includes and excludes:
    • Include domain specified
      • if domain is included, and entity not excluded, pass
      • if domain is not included, and entity not included, fail
    • Exclude domain specified
      • if domain is excluded, and entity not included, fail
      • if domain is not excluded, and entity not excluded, pass
      • if both include and exclude domains specified, the exclude domains are ignored
    • Neither include or exclude domain specified
      • if entity is included, pass (as #2 above)
      • if entity include and exclude, the entity exclude is ignored

Supported Components

The following components are currently supported:

Component Type Name Description
alarm_control_panel SecuritySystem All security systems.
automation / input_boolean / remote / script Switch All represented as switches.
binary_sensor Sensor Support for co2, door, garage_door, gas, moisture, motion, occupancy, opening, smoke and window device classes. Defaults to the occupancy device class for everything else.
climate Thermostat All climate devices.
cover GarageDoorOpener All covers that support open and close and have garage as their device_class.
cover WindowCovering All covers that support set_cover_position.
cover WindowCovering All covers that support open_cover and close_cover through value mapping. (open -> >=50; close -> <50)
cover WindowCovering All covers that support open_cover, stop_cover and close_cover through value mapping. (open -> >70; close -> <30; stop -> every value in between)
device_tracker Sensor Support for occupancy device class.
fan Fan Support for on / off, direction and oscillating.
light Light Support for on / off, brightness and rgb_color.
lock DoorLock Support for lock / unlock.
media_player MediaPlayer Represented as a series of switches which control on / off, play / pause, play / stop, or mute depending on supported_features of entity and the mode list specified in entity_config.
sensor TemperatureSensor All sensors that have Celsius or Fahrenheit as their unit_of_measurement or temperature as their device_class.
sensor HumiditySensor All sensors that have % as their unit_of_measurement and humidity as their device_class.
sensor AirQualitySensor All sensors that have pm25 as part of their entity_id or pm25 as their device_class
sensor CarbonMonoxideSensor All sensors that have co as their device_class
sensor CarbonDioxideSensor All sensors that have co2 as part of their entity_id or co2 as their device_class
sensor LightSensor All sensors that have lm or lx as their unit_of_measurement or illuminance as their device_class
switch Switch Represented as a switch by default but can be changed by using type within entity_config.


Deleting the .homekit.state file

The .homekit.state file can be found in the configurations directory. You might need to enable view hidden files to see it.

  1. Stop Home Assistant
  2. Delete the .homekit.state file
  3. Start Home Assistant

Errors during pairing

If you encounter any issues during pairing, make sure to

  1. Stop Home Assistant
  2. Delete the .homekit.state file
  3. Edit your configuration (see below)
  4. Start Home Assistant
  default: warning
    homeassistant.components.homekit: debug
    pyhap: debug

      - demo.demo

PIN doesn’t appear as persistent status

You might have paired the Home Assistant Bridge already. If not, delete the .homekit.state file (guide).

Home Assistant Bridge doesn’t appear in the Home App (for pairing)

For Docker users: make sure to set network_mode: host. Other reasons could be network related. Make sure to check your router configuration. For some it helped when the Home Assistant device was using WIFI, not LAN. Remember that the iOS device needs to be in the same local network as the Home Assistant device for paring.

Pairing hangs - zeroconf error

Paining eventually fails, you might see and an error message NonUniqueNameException. To resolve this, you need to replace a specific file. See the following git issues for more details: home-assistant#14567 and home-assistant#17181

Duplicate AID found when attempting to add accessory

Two of your entities share the same entity_id. Either resolve this or configure the filter to exclude them.

Issues during normal use

Pairing hangs - no error

Make sure that you don’t try to add more then 100 accessories, see device limit. In rare cases one of your entities doesn’t work with the HomeKit component. Use the filter to find out which one. Feel free to open a new issue in the home-assistant repo, so we can resolve it.

Some of my devices don’t show up - Z-Wave / Discovery

See disable auto start

Accessory not responding - after restart or update

See device limit

Accessory not responding - randomly

Unfortunately that sometimes happens at the moment. It might help to close the Home App and delete it from the cache. Usually the accessory should get back to responding after a few minutes at most.

Accessories not responding / behaving unusual - Upgrade from 0.65.x

To fix this, you need to unpair the Home Assistant Bridge, delete the .homekit.state file (guide) and pair it again. This should only be an issue if you’re upgrading from 0.65.x or below.