Installation & Usage

Virtual environment



With openhabian the complete installation can be performed through the openhabian-config tool (option 2B).
HABApp will be installed into /opt/habapp, so it is the same as the installation described here.


On Windows use the python command instead of python3

  1. Navigate to the folder where the virtual environment shall be created (e.g.):

    cd /opt
  2. Create virtual environment (this will create a new folder “habapp”):

    python3 -m venv habapp
  3. Go into folder of virtual environment:

    cd habapp
  4. Activate the virtual environment


    source bin/activate


  5. Upgrade pip and setuptools:

    python3 -m pip install --upgrade pip setuptools
  6. Install HABApp:

    python3 -m pip install habapp
  7. Run HABAp:


    A good configuration folder for HABApp would be your openhab configuration folder (e.g. /opt/openhab/conf/habapp or /etc/openhab/habapp) because this is where your other configuration folders are located (e.g. the items and sitemaps folder). Just make sure to manually create the folder habapp before the start.


After the installation take a look how to configure HABApp. A default configuration will be created on the first start.


  1. Stop HABApp

  2. Activate the virtual environment

    Navigate to the folder where HABApp is installed:

    cd /opt/habapp

    Activate the virtual environment


    source bin/activate


  3. Run the following command in your activated virtual environment:

    python3 -m pip install --upgrade habapp
  4. Start HABApp

  5. Observe the logs for errors in case there were changes

Autostart after reboot

Check where habapp is installed

which habapp

To automatically start HABApp from the virtual environment after a reboot call:

nano /etc/systemd/system/habapp.service

and copy paste the following contents. If the user which is running openhab is not “openhab” replace accordingly. If your installation is not done in “/opt/habapp/bin” replace accordingly as well:


ExecStart=/opt/habapp/bin/habapp -c PATH_TO_CONFIGURATION_FOLDER


Press Ctrl + x to save.

Now execute the following commands to enable autostart:

sudo systemctl --system daemon-reload
sudo systemctl enable habapp.service

It is now possible to start, stop, restart and check the status of HABApp with:

sudo systemctl start habapp.service
sudo systemctl stop habapp.service
sudo systemctl restart habapp.service
sudo systemctl status habapp.service

Error message while installing ujson

Under windows the installation of ujson may throw the following error but the download link is not working. Several working alternatives can be found here.

Running install for ujson ... error
  ERROR: Complete output from command 'C:\Users\User\Desktop\HABapp\habapp\Scripts\python.exe' -u -c 'import setuptools, tokenize;__file__='"'"'C:\\Users\\User\\AppData\\Local\\Temp\\pip-install-4y0tobjp\\ujson\\'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);'"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record 'C:\Users\User\AppData\Local\Temp\pip-record-6t2yo712\install-record.txt' --single-version-externally-managed --compile --install-headers 'C:\Users\User\Desktop\HABapp\habapp\include\site\python3.7\ujson':
  ERROR: Warning: 'classifiers' should be a list, got type 'filter'
  running install
  running build
  running build_ext
  building 'ujson' extension
  error: Microsoft Visual C++ 14.0 is required. Get it with "Microsoft Visual C++ Build Tools":

Error message while installing ruamel.yaml

_ruamel_yaml.c:4:10: fatal error: Python.h: No such file or directory

Run the follwing command to fix it:

sudo apt install python3-dev



Installation through docker is also available:

docker pull spacemanspiff2007/habapp

To have the proper timestamps in the logs set the TZ environment variable of the container accordingly (e.g. TZ=Europe/Berlin).

Updating docker on Synology

To update your HABApp docker within Synology NAS, you just have to do the following:

On the Synology NAS just select “Download” with tag “latest” to download the new image. It will overwrite the old one on the NAS. Then stop the container. After selecting “Action” -> “Clear” on the HABapp container, the container is there, but without any content. After starting the container again, everything should immediately work again.

Upgrading to a newer version

It is recommended to upgrade the installation on another machine. Configure your production instance in the configuration and set the listen_only switch(es) in the configuration to True. Observe the logs for any errors. This way if there were any breaking changes rules can easily be fixed before problems occur on the running installation.

HABApp arguments

Execute habapp with “-h” to view possible command line arguments

habapp -h
usage: -c [-h] [-c CONFIG] [-wos WAIT_OS_UPTIME] [-b] [-di]

Start HABApp

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Path to configuration folder (where the config.yml is
  -wos WAIT_OS_UPTIME, --wait_os_uptime WAIT_OS_UPTIME
                        Waits for the specified os uptime before starting
  -b, --benchmark       Do a Benchmark based on the current config
  -di, --debug-info     Print debug information