Using Python plugins

Overview

Plugins are great! Since the ability to create Python plugins was added to Domoticz, it has seen an explosion of plugins.

- Check this list of plugins that have already been developed and where to find them. Brand new plugins are also shared on the forum.
- Would you like to create your own plugin? This page will get you started developing plugins to extend the functionality of Domoticz.

Required: install Python

If you want to use plugins you must have Python 3.4 until 3.9 installed. 3.10 is still under test but seems to work.

• Check menu Setup - About Domoticz if Python is already recognized on your system.
• install python3 runtime (see sections below) if needed (preinstalled on a lot of Linux distro's)
  • you may need to install python3 development libraries for now
• restart your Domoticz service or complete system
• check your logs about Python installation or check menu Setup - About Domoticz. python version should be shown.

Installing Python on Linux Debian (eg Raspberry Pi with Raspbian)

Key point: Your version of Linux will come with a default version of Python3, if it is above 3.4 then use it. You can ignore python2.7 if it is already installed, it will be ignored.

Domoticz actually uses a package called libpython and this can cause some confusion. Just because python3 works does not mean libpython is on your system.

Check you do actually have a version of Python3, it will tell you if it is installed already:

 sudo apt install python3

Check the version:

 python3 -V

Make sure that you have libpython installed, it needs to match the version you have. If you have Python 3.4.x then you make sure you have libpython3.4, if you have Python 3.5.x then you make sure you have libpython3.5 and so on. Use this command to check:

 dpkg --get-selections | grep libpython

If it is not there then use (where 'x' is the version from above: e,g libpython3.4 or libpython3.5 etc):

 sudo apt install libpython3.x

If you still do not see the python version in Domoticz menu Setup - About Domoticz please install python3-dev:

 sudo apt install python3-dev

Restart Domoticz.

Python plugins are supported in the current Domoticz stable version.

Installing Python for Windows

• If you are using the precompiled x86 version of Domoticz from https://www.domoticz.com/downloads/ , install the 32 bit Python version even if your Windows is 64 bit.
• Currently Python 3.7 to 3.13 is supported.
• Do not install Python 3.8.0 as this will stop the plugin framework. Install 3.8.1 or higher!

Installing a plugin

NOTE: On newer linux distros like Bookworm, Trixie, Ubuntu 24 , Debian 12, -13 etc, you have to setup a Python Virtual Environment (venv) when extra python modules are needed by the plugin. See for instructions below

Generally installing a plugin takes a few steps:

• Download the plugin and copy its folder into the domoticz/plugins directory. Each plugin at the very least consists of a plugin.py file. Downloading is normally done with a git clone command from the plugin repository.

NOTE: On Windows the domoticz/plugins directory has to be created manually. It is not created by the installation script.

• Give the plugin.py file execute permissions. Right click on the file to change its permissions, or use the terminal to navigate to the directory, and then type: sudo Chmod +x plugin.py
• Restart the Domoticz service (or reboot the entire server)
• In the Domoticz interface, navigate to the hardware page, menu Setup - Hardware. There you should now find the plugin name in the device types dropdown list for adding new hardware gateways.

Optionally, you may have to install extra software like drivers. Check the plugin documentation to find out.

Setting up a Python Virtual Environment (venv) for module install

Newer Linux distros adheres to PEP 668, which marks the system Python environment as "externally managed," making it difficult to install packages system-wide using pip without potential conflicts or breaking system utilities. So we need to setup a Python venv when extra Python modules are needed by the plugin (see the plugin install instructions to check if extra modules are needed)

• Create a folder in your home eg /home/pi/Domoticz_Python_Environment and make it a Pytrhon venv by running the following commands in a terminal session:
  1. cd /home/pi (change your username accordingly)
  2. mkdir Domoticz_Python_Environment (this can be any name)
  3. python3 -m venv Domoticz_Python_Environment source Domoticz_Python_Environment/bin/activate
  4. pip install --upgrade pip
  5. Make Domoticz start with the Python Environment:
     1. If you are running Domoticz as a service with the init.d feature, you can simply edit the /etc/init.d/domoticz.sh file and add an extra line: export PYTHONPATH=/home/pi/Domoticz_Python_Environment:$PYTHONPATH
     2. If you run Domoticz with systemd, If you want to set some specific environment variable for the execution of the domoticz daemon, you can use the filename specified in the EnvironmentFile clause to do so. Here for example, we are setting the PYTHONPATH to use a local python environment:
        • vi /home/pi/domoticz.env
        • PYTHONPATH="/home/pi/Domoticz_Python_Environment/:$PYTHONPATH"
     3. As you are changing a startup script, in both options you have to run systemctl daemon-reload

Install the python modules with pip install as needed when the venv is still active

When you close the terminal session the Python venv is deactivated for module installation. So when you need to install Python modules for eg another plugin you have to enable it again in the new terminal session with command:

/home/pi/Domoticz_Python_Environment/bin/activate

Then you can install the extra modules again with pip install

Example plugin install for Raspberry Pi with Raspbian (without Python venv)

Let's run through an example installation.

A lot of plugins store their code on Github, a website made for this purpose. If you run Domoticz on a Linux system, install Git to easily download the plugins through the terminal:

 sudo apt-get update
 sudo apt-get install git

Next, navigate to the plugin directory, and install the plugin straight from Github. In the documentation of most plugins you'll find the Git link you an use. Here we install the Smart Virtual Thermostat in a folder called 'SVT':

 cd domoticz/plugins
 git clone https://github.com/999LV/SmartVirtualThermostat.git SVT

So in this case the directory structure should now be: domoticz/plugins/SVT/plugin.py

Next, we restart Domoticz so that it will find the plugin:

 sudo systemctl restart domoticz.service

From here the plugin should be able to be set-up from the Domoticz interface. Go to the hardware page and look in the dropdown. Note: the plugin and directory name are often different.

If you run Linux and the plugin does not show up in the hardware list, you may have to make the plugin.py file executable. Let's enter the directory and issue the command:

 cd SmartVirtualThermostat
 chmod +x plugin.py

Restart Domoticz and it should now show up.

Plugins when using Docker

When launching the docker container for the first time, a plugin folder is created in the mounted /opt/domoticz/userdata folder You need to place your python plugins in this folder.

The stable container runs Python 3.11.2. (current beta too)

When plugins need extra python modules you need to install those in the Docker container! Python is also setup with a venv so no need to do something special on installing the required python modules. You can use the custom startup script (see Docker) to be sure the required python modules are reinstalled when you update the docker image.

Troubleshooting

• check the log via the web interface (Setup / Log)
• you should see

PluginSystem: Started, Python version '3.x.y'

• if there is no mention at all of plugins
  • Check Setup > Settings > Other (tab) > EventSystem(LUA/Blockly/Scripts) > Enabled is ticked
  • check have set up plugins (see above)
• if you see

PluginSystem: Failed dynamic library load

• • have you installed the pyhton3 development libraries
  • check article [1]

To find which version is active (3.4 or 3.5), type this command:

 python3 -V

If you wamt to change versions, try something like this:

 sudo apt-get install python3.4 libpython3.4 python3.4-dev

Next, set 3.4 as the main version to use. You can change it back later if you want.

 update-alternatives --install /usr/bin/python python3 /usr/bin/python3.5 1
 update-alternatives --install /usr/bin/python python3 /usr/bin/python3.4 2

Now you can switch between them by issueing this command, and selecting your preference:

 update-alternatives --config python3

More details on telling linux which version of Python to use: https://linuxconfig.org/how-to-change-from-default-to-alternative-python-version-on-debian-linux

Installing Modules fails

In newer Linux OS's Python is defaulting to virtual python environments (venv). This can result in error message "error: externally-managed-environment" when installing Python modules with pip or pip3

The dirty way is to add --break-system-packages at the end of the pip3 install module or requirements command line.

For example

sudo pip3 install -r requirements.txt --break-system-packages

Alternative and better is to make use of Python Virtual Environment, install the modules in that environment and add the definition for the PYTHONPATH environment variable in the script which automatically starts Domoticz.

See for instructions (written for the Zigbee4Domoticz but could be used for any plugin):

https://zigbeefordomoticz.github.io/wiki/en-eng/HowTo_PythonVirtualEnv.html

Importing Modules fails

If a module is not found the Plugin Framework will provide as much information as it gets from Python. For example, an attempt to import fakemodule in a plugin called 'Google Devices' will be reported like this in the Domoticz log:

 2019-03-23 17:17:44.483  Error: (GoogleDevs) failed to load 'plugin.py', Python Path used was '/home/domoticz/plugins/Domoticz-Google-Plugin/:/usr/lib/python36.zip:/usr/lib/python3.6:/usr/lib/python3.6:/usr/lib/python3.6/lib-dynload:/usr/local/lib/python3.6/dist-packages:/usr/lib/python3/dist-packages:/usr/lib/python3.6/dist-packages'.
 2019-03-23 17:17:44.483  Error: (Google Devices) Module Import failed, exception: 'ModuleNotFoundError'
 2019-03-23 17:17:44.483  Error: (Google Devices) Module Import failed: ' Name: fakemodule'
 2019-03-23 17:17:44.483  Error: (Google Devices) Error Line details not available.

The framework shows the directories it searches. Broadly these are: the plugin directory, the existing Python path as picked up when Domoticz started and the 'site' directories for system level modules installed with pip3. Local 'site' directories are not searched by defaul although plugin developers can add any directory the like to the path inside the plugin.

Pip3 installs packages in system directories when sudo is used on linux platforms. So if Importing fails try to install library with sudo pip3 "python module"

For Windows use python -m pip install "python module"