
stable9 is the current production branch of the plugin. stable8 is out of support and locked: it receives no more updates, not even bug fixes. All development continues on stable9, which is built exclusively on the Domoticz Extended Framework (DomoticzEx), available since Domoticz 2025.1.
The switch is done with a single tool provided in the plugin itself: Tools/plugin-switch-stable9.sh. Do not switch branch manually with git checkout stable9 — this script checks your Domoticz version, shows you the migration notice, and only proceeds once you’ve explicitly acknowledged it.
stable8 keeps working exactly as before.stable9. Such new devices are not compatible with stable8’s legacy widget model.stable9, going back to stable8 stops being an option.Only run the switch once you’re ready to commit to stable9.
Still on stable7? Follow Upgrading from stable7 to stable9 instead: it goes straight to stable9.
Do this before anything else, before the backup and before the switch. stable9 needs:
stable9 refuses to start (Z4D requires Python 3.11, found 3.9). The switch tool does not check the Python version.stable8 itself runs with Python 3.9 and Domoticz 2023.1, so a working stable8 installation doesn’t prove that your system is ready.
The Python version Domoticz runs with. Look for these lines in the Domoticz log at start-up:
Status: PluginSystem: Started, Python version '3.9.2', 10 plugin definitions loaded.
Status: Zigbee: Z4D requires python3.11 or above and you are running 3.9
The first one comes from Domoticz, the second one from the stable8 plugin (Zigbee is the name of your plugin hardware). The version of python3 in a terminal is not always the one Domoticz uses: rely on the log. See Find the Python version of Domoticz.
The Domoticz version, in Setup > About.
Then:
| Your system | What to do |
|---|---|
| Python 3.11 or newer and Domoticz 2025.1 or newer | Go on with the prerequisites and Step 1. |
| Python 3.11 or newer, Domoticz older than 2025.1 | Upgrade Domoticz first (2026.3 recommended), then check the Python version in the log again. |
| Python 3.10 or older (Debian 11 Bullseye or older, Raspberry Pi OS Bullseye or older, Ubuntu 22.04 or older) | Don’t switch. Your system is too old for stable9: move to a new system as described in Path B of the stable7 page. It applies to stable8 in the same way. |
Docker (official domoticz/domoticz image) |
The image comes with a recent Python. Update the image to Domoticz 2025.1 or newer first. |
These distributions don’t provide Python 3.11, and recent official Domoticz builds no longer run on them (they need OpenSSL 3). Building your own Python or Domoticz on an old distribution is not supported by the plugin team.
plugin-switch-stable9.sh checks the Domoticz version again through the Domoticz JSON API, and refuses to switch if it is too old. Domoticz 2026.3 is the recommended version for the best experience with the Extended Framework.stable8, with no uncommitted local changes (git status clean). Commit or stash anything pending first.Because this move is one-way as soon as you pair a new device (see above), take a full backup before switching, not after:
domoticz.db) itself.Back up the plugin’s critical files, at the same time as the database so the two stay consistent — see Plugin Backup for the full list and procedure:
Conf/PluginConf-*.json
Data/*
Reports/*
This way, if anything looks wrong right after the switch, you can restore both the database and the plugin files and be back exactly where you started — as long as you haven’t paired a new device yet on stable9.
Domoticz (and the plugin) must be up and running at this point — the script checks your version by calling Domoticz’s own JSON API, so it needs to be reachable. If you stopped Domoticz for the backup in Step 1, restart it first.
From your plugin directory (the one containing Tools/), run the script with no arguments:
Tools/plugin-switch-stable9.sh
This:
127.0.0.1:8080 (the default) to confirm your version supports the Extended Framework.If Domoticz runs on a different host/port, pass --ip and --port:
Tools/plugin-switch-stable9.sh --ip 192.168.1.10 --port 8080
If you run Domoticz in Docker and invoke the script from the Docker host (not via docker compose exec), 127.0.0.1 on the host only reaches Domoticz if that port is published to the host. Either:
run the script inside the container, matching the pattern used by Tools/update_domoticz_docker_container.sh, e.g.:
docker compose exec <container> bash -c "cd <plugin_dir> && Tools/plugin-switch-stable9.sh"
or pass --ip/--port matching the host-published address.
If the script cannot reach Domoticz at all, it falls back to asking you to confirm the version manually via Setup > About in Domoticz rather than assuming success.
Domoticz (and the plugin) must still be up and running — the script re-checks your Domoticz version the same way it did in Step 2. Keep it running afterward too: Step 4’s WebUI upgrade is a plugin action, so it isn’t possible unless Domoticz and the plugin are up.
Once you’ve read the notice and are ready to proceed, re-run the script with --i-understand:
Tools/plugin-switch-stable9.sh --i-understand
This is the only flag that actually triggers the switch — it’s meant to be typed explicitly, on the command line, by a person who read the notice. The script then:
git fetch origin and pulls the latest changes on your current branch.stable9 and pulls its latest changes.On success you’ll see:
Successfully switched to stable9 branch
along with the same one-way reminder from the notice above.
plugin-switch-stable9.sh only switches the git branch — it does not install/upgrade Python dependencies. stable9 can require newer module versions than stable8, so before restarting, use the plugin’s own upgrade action to bring the Python environment in line:
requirements.txt for the stable9 code now checked out (see Plugin Update), using whichever Python environment the plugin itself is configured to run under — including a venv, if you use one.Use the WebUI action rather than running pip install yourself from a terminal: a manual pip install targets whatever python3 resolves to in your shell, which may not be the same interpreter/venv Domoticz actually runs the plugin with.
git stash -u), then re-run the script.stable9 otherwise.Z4D requires Python 3.11, found 3.9 after the restart: Domoticz runs with a Python that is too old for stable9 (see Step 0). You can’t fix it with the plugin: move to a new system as in Path B of the stable7 page, or go back to stable8: git checkout stable8, then restore the backup of Step 1.--ip/--port, or confirm your version manually via Setup > About, then re-run with --i-understand once you’re sure.