How to best update from 3.3.0 to 4.0.2?

I have a manual 3.3.0 installation on Linux and I wonder what is better/less error-prone:

  • update 3.3.0 first to 3.4.5, check/fix everything and then update to 4.0.2
  • update 3.3.0 directly to 4.0.2


first update to 3.4.5, then hold version, upgrade system to current version (which Distro? Hardware?), check that openHAB3.4.5 is still working, then update to Java17 (openHAB3.4 is Java17 compatible).
After updating to Java17 (and openHAB3.4.5 still working…) , unhold the openHAB version and upgrade to 4.0.2, which will result in an upgrade with automatic changes in configuration - of course you will still have to care about some parts of the configuration.

1 Like

Thanks for the quick response.
This is a manual installation (no openHAB distro) on Gentoo Linux.
So, I should first update to 3.4.5 and check that everything is working and then do the next update to 4.0.2.

Yes, for sure.
In fact, this is the correct way to do it even on an openHABian (i.e. the only official openHAB “distro-like” thing) system.

1 Like

Cool, thanks!

I’m running v3.3, how do I first upgrade to 3.4.5? If I use openhabian-config I’m afraid I get v4.0, isn’t it? Thx

I’m not sure if there is an easy way with openhabian-config, but you can use apt to do it:

sudo apt update
apt-cache showpkg openhab | grep 3.4.5

this should result in a list of all available versions with 3.4.5 in the name. Select the highest available version (not sure, maybe 3.4.5-2?)
For example, sudo apt install openhab=3.4.5-2 will install version 3.4.5 (patch 1, as -1 is the unpatched version)

Please take a look at the ChangeLogs:

please take care of EVERY change log since 3.3.0 (no need to read entirely, but search for every breaking change and every binding you are using)
Keep in mind that the releases are not sorted as version ascending but as publishing date ascending, so there are many 4.0.x versions between all releases from 3.3.0 to 3.4.5

1 Like

Thanks this was really helpful and worked.

I’m facing a similar situation and have an additional question.
I’m currently running 3.3.0 on Windows 10 and want to upgrade to the latest stable 4.1. I understand that I first have to upgrade to the latest 3 version, then upgrade to Java 17. What I don’t understand is the “hold version” step. Is this to prevent automatic updates of add-ons and bindings? If this is a necessary step, hjow do I do this on a Windows platform?
Thanks for any explanations.

The hold step does not apply for windows 10.
The whole point is, when upgrading the OS debian 10 (buster) to debian 11 (bullseye), it will upgrade openHAB to the current version, too, as openHAB is just a software package.
So as a Windows user:

  • Backup your configuration
  • upgrade to OH3.4.5
  • check if anything went wrong
  • do another backup (just in case…)
  • install Java17
  • Upgrade to OH4.1
  • do another check

There may be no big issues from 3.3 to 3.4.5, but it’s very likely that some parts of your configuration have to be changed to get it up and running after upgrading to 4.1.

Thanks Udo. That clarifies things.
Yes, I will need to look at the new UoM handling. Honestly, not looking forward to that, as I’ve had fun and games getting my Raffstores to work properly with mismatching ranges (1 … 100 vs. 0…255) mixed with percentages. But, who knows, perhaps the new approach will make things easier.

Guten Rutsch!

1 Like


Does the upgrade from 3.4.5 to 4.1.1 via the deb package handle all changes in config files, like the split and so?



In question of configs set via Main UI, then yes, the upgrade process will take care of (most) configuration changes.
On the other hand, nothing which is setup via text files (the ones in $OPENHAB_CONF/ directory) will be changed, it’s up to you to take care of.

Ok, thanks! I only use the GUI…

BTW, is there a documentation on how to backup/restore an OH config?

If we’re talking about GNU/Linux, just use

sudo openhab-cli backup


sudo openhab-cli restore </path/to/your/>

For windows, there should also be a similar command (located in runtime\bin\ if i got it right)
For docker installations just backup the volumes yourself :slight_smile:

Hi all, I have OH 3.3 on docker. Should I need to follow the same steps (3.3 to 3.4.5 and then 3.4.5 to 4) or, considered my docker config, I can avoid the middle step ?
Thanks !

I highly recommend to update to 3.4.5 first, when using docker it’s a no-brainer (just update and take a closer look if there are any issues) and afterwards the internal upgrade scripts to 4 should work flawless.

1 Like