Python library not working as intended in Ubuntu 22

[gnastacast]

For some reason in Ubuntu 22 (which supports Ros2 Humble Hawksbill) the hebi library is broken when installed through pip. This is true for both the default pip (22) and the newest pip at the time (26)

Instructions to reproduce

docker container run -it ubuntu:jammy /bin/bash
apt-get update
apt install python3-pip
pip install hebi-py
python3 -m hebi

produces the output

/usr/bin/python3: No module named hebi

This works fine in ubuntu 24.04 (Noble)

docker container run -it ubuntu:noble /bin/bash
apt-get update
apt install python3-pip
pip install hebi-py --break-system-packages
python3 -m hebi

produces the expected output

matplotlib not found - hebi.util.plot_logs and hebi.util.plot_trajectory will not work.
pynput not found - HebiKeyboard will not work
/usr/bin/python3: No module named hebi.__main__; 'hebi' is a package and cannot be directly executed

It breaks again in ubuntu 26.04 (Resolute) but this seems to be a different issue.

[HEBI Warning] Unable to load (library=hebi).
[HEBI Warning] Candidate libraries attempted (in order):
[HEBI Warning] Candidate 1: /usr/local/lib/python3.14/dist-packages/hebi/lib/linux_x86_64/libhebi.so.2.24
[HEBI Warning] Candidate 2: /usr/local/lib/python3.14/dist-packages/hebi/lib/linux_x86_64/libhebi.so.2
[HEBI Warning] Candidate 3: /usr/local/lib/python3.14/dist-packages/hebi/lib/linux_x86_64/libhebi.so
Traceback (most recent call last):
  File "<frozen runpy>", line 189, in _run_module_as_main
  File "<frozen runpy>", line 148, in _get_module_details
  File "<frozen runpy>", line 112, in _get_module_details
  File "/usr/local/lib/python3.14/dist-packages/hebi/__init__.py", line 10, in <module>
    from ._internal.ffi import loader as __loader
  File "/usr/local/lib/python3.14/dist-packages/hebi/_internal/ffi/__init__.py", line 1, in <module>
    from .loader import _handle
  File "/usr/local/lib/python3.14/dist-packages/hebi/_internal/ffi/loader.py", line 240, in <module>
    _handle = _init_libraries()
  File "/usr/local/lib/python3.14/dist-packages/hebi/_internal/ffi/loader.py", line 234, in _init_libraries
    core_lib, core_loc = _load_core_shared_library()
                         ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/local/lib/python3.14/dist-packages/hebi/_internal/ffi/loader.py", line 173, in _load_core_shared_library
    def _load_core_shared_library(): return _load_shared_library('hebi', 'HEBI Core', 'HEBI_C_LIB')
                                            ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/dist-packages/hebi/_internal/ffi/loader.py", line 167, in _load_shared_library
    raise RuntimeError(f'{readable_name} library not found')
RuntimeError: HEBI Core library not found

[iamtesch]

Thanks for the report -- we're looking into this now, and will let you know as soon as we have more info or follow up questions!

[iamtesch]

Ok, some progress here in the Ubuntu 22 case. I can repro the issue here, in and out of the Docker container with an ubuntu 22 machine. It looks like there are some issues with Ubuntu 22 + Python in terms of which system directories are writeable, and package installs can silently fail in a sort of half-installed state. I've tried to update setuptools, which some users had success with, but this did not resolve the issue for me.

That said, for the Ubuntu 22 case, I also have a (potential) workaround. If possible to use a virtual environment, this allows the install to complete successfully. So you can run:

docker container run -it ubuntu:jammy /bin/bash
apt-get update
apt install python3-pip python3-venv
python3 -m venv myenv
source myenv/bin/activate
pip install hebi-py
python -m hebi

And this yields the expected result for me. I haven't tried with uv, another virtual environment tool, but I expect this would work as well.

Potentially related issue from another project here: easybuilders/easybuild-easyblocks#2976

I'm guessing a more full solution involves some updates to our packaging process, but I'm not sure exactly where the error is yet. We'll keep you posted there.

[gnastacast]

Great! Thanks. I'm not sure how well that will play with ROS since I have had trouble linking with virtual environments in older versions but hopefully that should do it. Also this is Nico ⊂(◉‿◉)つ I am somehow doing snake stuff again.

[iamtesch]

Yeah, I was afraid virtual environments might not work well with ROS. I think I have a workaround with a manual install that doesn't require this:

First, download the raw .tar.gz file from
https://files.pythonhosted.org/packages/24/0c/e6f636bb9b18d905960073868ec5402cce8b93e3012a9cffa7736ba90e22/hebi_py-2.14.1.tar.gz

You can untar it with:

tar -xzvf hebi_py-2.14.1.tar.gz

and it will create a hebi_py-2.14.1 folder

Then, after the pip install hebi-py line, copy the hebi folder from that hebi_py-2.14.1 folder you extracted into the local python install directory:

cp -r hebi_py-2.14.1/hebi ~/.local/lib/python3.10/site-packages/

You should then be able to use the HEBI Python package normally...

---

Still struggling with the Ubuntu 26 case here as well. To save you time testing there, the venv trick doesn't work.

The package is installed file on 26, but it's not allowing Python to load the (valid, on disk, correct path) library. My best guess is that they added an "AppArmor" security measure in Ubuntu 26, and so loading libraries dynamically is a bit more protected now. Unfortunately, from what I've read I'm not sure how it plays with Docker, and if this even comes into play on a Docker 26 image run on a 22 box...

I don't have a pure 26 box set up, but we'll keep plugging away at this and track down what's going on. Sorry for the trouble.

And you should come stop by the office sometime -- it'd be good to catch up again!

[gnastacast]

Thanks for all your help!