Correct approach of installing an addon.jar over an installed one in the addon-folder

I was always wondering what is the right way of updating a jar-file in the addons folder. I checked the documentation but I couldn’t really find a documentation about the right approach.

When copying an updated jar file I do notice that it is automatically loaded. Though when I look into karaf console, I see both, the old and new, bindings being active. I wonder how they are both being used?

So, here are my questions:

  • what happens if both bindings (the default installed and the updated jar in the addons folder) are loaded by karaf and are active? Which one is used by which thing?

  • what is the correct and clean way to install a new binding? Is the following really necessary or can it be simplified?

    • run “openhab-cli console”
    • find the binding
bundle:list | grep mybindingname
303 │ Active │  80 │ 3.4.0.M6               │ openHAB Add-ons :: Bundles :: mybindingname Binding
  • next steps
    • bundle:stop 303
    • logout

Now all things will fail because they will be missing their handler

  • only then copy the new jar file to the addons folder (binding will be loaded and all things should become “online” again.

  • or alternatively

    • uninstall the binding with the UI
    • the copy the jar to the addons folder while openhab is running
  • or in both case before copying the jar file to the addons folder, stop openhab first, the copy the file, then restart openhab

  • or even use bundle update (though I don’t know how to use it)

I am happy to document the right approach here: Bundle Management | openHAB

I prefer to tell openHab exactly what to do, so I use bundle:update. In my experience (Z-Wave and Zigbee Binding) this command is sufficient for a bundle update.

bundle:update seems to be defined in in OSGi Core.

openhab> help bundle:update

    Update bundle.

        bundle:update [options] id [location]

                The bundle ID or name or name/version
                The bundles update location

                Display this help message
                Use the given bundle context
                (defaults to 0)
                Do not update the bundles's Bundle-UpdateLocation manifest header
        -r, --refresh
                Perform a refresh after the bundle update

Thanks, I appreciate your input! :+1:

So I would think in your case, only one bundle will be active at the same time, correct?
Do you know what happens when two bundles are active, though?

btw, bundle:update is available at least in my current setup which is M6.

It’s almost certainly “bad things”, probably unpredictable, depending on the code.

1 Like

How do you use bundle update if you want to install a file that you have locally?

I tried the following

bundle:update 303 /tmp/org.openhab.binding.mybindingname-3.4.0-SNAPSHOT.jar

and I get a

Error executing command: URI is not absolute

Hence, this only seems to work if you can access via a URL?

In the case of openHAB core bundles as well as JavaScript Scripting, the jar is loaded and the bundle therefore activated by Karaf. This leads to serious problems, e.g. JavaScript Scripting attempting to load every script file two times, which leads to other problems.

Most times, my approach doesn‘t require an openHAB restart (except for core bundles sometimes) (for JS Scripting I never needed a restart).
My approach is the following:

  1. Put the jar/kar file in the addons folder.
  2. Log into the openHAB console and run the following commands (example for JS Scripting):
    2.1. bundle:list org.openhab.automation.jsscripting:
START LEVEL 100 , List Threshold: 50                                                                                                
 ID │ State   │ Lvl │ Version            │ Name                                                                                     
263 │ Active  │  80 │ 3.4.0.M6           │ openHAB Add-ons :: Bundles :: Automation :: JavaScript Scripting                         
307 │ Waiting │  80 │ │ openHAB Add-ons :: Bundles :: Automation :: JavaScript Scripting

2.2. As you can see, the M6 bundle is active, but I want to use the jar version.
2.3 I then uninstall (stopping doesn‘t work over an oh restart) the M6 bundle: bundle:uninstall 263
2.4. Finally, I restart my jar bundle: bundle:restart 307

I haven‘t got it working with files until now, but I‘ve already used this with URLs to online artifacts.

@stefan.hoehn Could you try it with bundle:update 303 file://tmp/…

@J-N-K Do you know a good solution here?

1 Like

Historically I followed this path (assumed nothing good could happen with two bundles running) but have recently tried the bundle:update option. The question I have is where is this new bundle stored? Will this method survive a clean-cache/OH upgrade or will the original version (or the bundle in the new kar) be reinstalled?
I have a modified zwave jar that I use across OH upgrades (sometimes have to change due to core changes). I also have a related question about the local file. Can the bundle:update (maybe like bundle:update file:// work across the LAN? I use my windows to compile the jar that runs on a pi. Right now I just use Samba to move to the addons folder.

PS: Good topic


Actually, @florian-h05 and @apella12, this actually has worked flawlessly :tada:


bundle:list | grep My
303 │ Active │  80 │ 3.4.0.M6               │ openHAB Add-ons :: Bundles :: My Binding
openhab> bundle:update 303 /srv/openhab-sys/

Note: I put the binding one directory above the addons-folder, though the question is still valid what would happen on a openHAP update.


bundle:update 303 file:///localhost/srv/openhab-sys/

openhab> bundle:list | grep My
303 │ Active │  80 │     │ openHAB Add-ons :: Bundles :: My Binding

What is even nicer, compared to the update that I did in the past, is that the binding keeps its ID and I don’t have two instances of the binding at the same time.

Looks like a pretty good approach so far and I would say we should document that (I am happy to do that).

But before I do, I’d love to hear other’s voices as well (@wborn , @kai, @hmerk , @J-N-K, @laursen + everything has also some other experiences… sorry for pinging :slight_smile: ) :pray:


RFC 3986 specifies URI, e.g. file:///tmp/…

Good catch, thanks. I edited it above.

It depends.


Generally the approach with bundle:update is the correct way to update bundles (this also works for core-bundles). The drawback is that updated bundles MAY revert to the originally installed version if you install another add-on.

Please note that using uninstall for a bundle will most probably NOT work, because all add-ons bundles are part of a feature and as long as the feature is installed, the bundle will likely be reinstalled.

Installation in addons-folder:

If it’s just about add-ons, it’s also fine to uninstall it and then put the .jar in the addons-folder. You don’t need to restart openHAB, just uninstall, wait until uninstall has completed and then drop the new file in the addons-folder.

You may run into problems in this case if the add-on depends on some non-standard feature (e.g. knx depends on the feature openhab-transport-serial). These features are automatically installed if you install an add-on (via UI or addons.cfg) and are also uninstalled if there is not add-on using it. If that is the case, you have to install the feature manually with feature:install openhab-transport-serial (preferred way) OR drop the required bundles in the addons-folder, too.


Well, I don’t think, there is a “best” appoach.
When using updated binding versions, or versions not beeing merged, I don’t even download them to my openHAB server, but mostly use the github link or wherever the author hosts the jar


Same for update

 bundle:update 310
1 Like

Thanks Jan (and Jörg),

One thing that I am still interested in is regarding the installation via the addon folder:

What I often see is that there is the “original” bundle active (that was originally installed via the GUI) plus the new one that has been copied to the folder as well (where I then would stop the old one).

  • Do you know how these bundle instances are related to the thing(s) instances that are currently loaded? Will the things be bound to the new bundle or do still related to the old one? Can I safely expect that all things are using the new bundle?

  • Does it make more sense to first uninstall the bundle via the GUI and only then copy the jar to the folder?

  • What happens if I hadn’t uninstalled the bundle via OH (so OH “knows” that I have this bundle installed) and I have a (snapshot) version in the addon folder which is currently used and I then upgrade OH which brings along a new version of that bundle (in the KAR file)? Will it use the one in the KAR or the one that I have copied into the addons folder?

No one can clearly say what happens if you install two versions of the same bundle. But as @rossko57 already said: almost certainly this will end with a lot of trouble. The same applies to the third situation.

As I said: uninstall the add-on (from UI or addons.cfg, wherever you installed it), THEN drop the new file in the addons-folder.

1 Like

Ok, thx,

do you mind (Jörg and Jan), if I take what you wrote, put it together and add it to the following page?

Bundle Management | openHAB

Feel free…

Here’s something interesting that I just noticed:

I was on an openHAB snapshot version and had copied a bundle that I had compiled to the addons folder which was then used by my installation and worked fine for some days.

I intentionally left it there and upgraded to the next milestone (RC1) and the result was that OH then did not use the one in the addons folder but the one that came along with RC1 which then allowed me to delete it from the addons folder without any noticeable side effect.

Not sure if that karaf noticed that the one from RC1 was never than mine but the experience was a pretty smooth one.

documentation Pull Request:

If you uninstalled the binding in question on the UI before adding a copy (duplicate) to the addons folder I do not see how an upgrade would bring back the uninstalled binding? I think you are flirting with the two addons running at the same time (IMO).

Regardless I would like to thank you for asking this question, particularly the option to update a locally produced/compiled file. I’m changing my approach to use the bundle:update. I can now avoid the openhab-transport-serial error I was getting on an OH upgrade (the clean-cache was deleting the feature). I may still have to go into karaf after an OH upgrade to update the binding back to the version I have locally, but it should happen without errors.

Hi Bob,

Good that you mention it. No, I hadn’t done that because I am always afraid to break something in my setup when I remove a binding from the UI (which is also probably not true).

I did that for the purpose of research only to see what would happen… :slight_smile:

The idea was to have it in the addons folder with my snapshot version, then bravely install the new OH with a new release of that addons and see what would happen. Of course, in the future I won’t do that.