Link Search Menu Expand Document

Home Assistant KNX Integration

XKNX is shipped within Home Assistant (HA), the great solution for home automation, in the form of the included KNX integration.

For development and debugging reasons - or to catch up with the newest features - you may still want to use the custom component version of the plugin.

Manual Installation:

Checkout xknx ideally into your home folder:

cd ~
git clone

Create a symbolic link to your custom components directory:

mkdir -p ~/.homeassistant
ln -s ~/xknx/home-assistant-plugin/custom_components/xknx ~/.homeassistant/custom_components

Run HA as usual either via service or by directly typing in hass.

Running HA with local XKNX library

When running HA with the KNX integrated component once, HA will automatically install a xknx library version within [hass-dependency-directory]/lib/python[python-version]/site-packages via pip. This very often causes the problem, that the manually checked out xknx library is not in sync with the xknx library version HA already contains and uses by default. But getting both in sync is easy:

Delete the automatically installed version:

rm [hass-dependency-directory]/lib/python[python-version]/site-packages/xknx*

Note: [hass-dependency-directory] is platform dependend (e.g. /usr/local for Docker image, ~/.homeassistant/deps for macOS or /srv/homeassistant for Debian).

Ideally start HA from command line. Export the environment variable PYTHONPATH to your local xknx checkout:

export PYTHONPATH=$HOME/xknx

Starting via service is also possible, but you have to change the configuration to make sure PYTHONPATH is set correctly.


The configuration for the manually checked out version works the same as described within Home Assistant KNX documentation with the difference that the integration and platform is called xknx instead of knx (which is the HA default KNX integration and platform name).

    host: ''

    - name: Kitchen-Light-1
      address: '1/0/9'
      brightness_address: '1/0/11'

    - name: Kitchen.Coffee
      address: '1/1/6'


If you have problems, join the XKNX chat on Discord. We are happy to help :-)

Table of contents