Self compiled OpenCV Python with Gstreamer on Windows is not imported properly

[timorkal]

I've built OpenCV Python from source with Gstreamer support on Windows 10 machine using Mingw64.
Everything is working well in my Python Virtualenv.
Though the only thing I need to add to my main.py code before the import cv2 is:
import os
os.add_dll_directory(GSTREAMER_PATH)
Where GSTREAMER_PATH is the 'bin" directory of where the Gstreamer is installed.
Without setting these lines I get this error:
ImportError: DLL load failed while importing cv2: The specified module could not be found.

Now when I try to package everything with PyInstaller it fails on the same error:

572 WARNING: Failed to collect submodules for 'cv2' because importing 'cv2' raised: ImportError: DLL load failed while importing cv2: The specified module could not be found.

For validation. I have tried to uninstall my own compiled OpenCV and install the Pypi one "opencv-python", then the Pyinstaller manages to package it properlly.
The problem using the Pypi one is that it doesn't come with Gstreamer support, so I must use my own.

I understand that PyInstaller automatically tries to use the hook-cv2.py. But looks that it doesn't handle properly such kinds of scenarios.

My environment versions are:
OS: Windows 10 x64.
Python: 3.11.
PyInstaller: 6.12.0.
Pyinstaller-hooks-conrib: 2025.1.
OpenCV: 4.11.0.
Gstreamer: 1.24.12

Any help please with how to import cv2 properly in my scenario?

[rokm]

572 WARNING: Failed to collect submodules for 'cv2' because importing 'cv2' raised: ImportError: DLL load failed while importing cv2: The specified module could not be found.

The package needs to be importable when PyInstaller tries to perform its import analysis. If that is not the case, you have an effectively defunct environment, and you cannot expect things to work.

In this case, you could probably append/prepend the path in GSTREAMER_PATH to PATH environment variable before running PyInstaller, so that GStreamer DLLs can be discovered when cv2 extension is imported.

---

But do note that we do not support collection of GStreamer (and its plugins and the registry file) in arbitrary scenarios; the only situation when this is performed automatically is when gi.repository.Gst is used (because the hook for that package performs the collection). So you will likely need to collect GStreamer files yourself, and probably also set paths to collected files at run-time via environment variables (similarly to what our run-time hook for gi.repository.Gst does), for example at the very start of your program.

[timorkal]

Thank you,

Regarding the collection of the GStreamer I am not worried, I don't use "gi" in my code, just cv2.
And I rely on the the target device to have GStreamer already installed so I can just point the GSTREAMER_PATH into that location during runtime.

Regarding the Pyinstaller cv2 packaging, the PATH environment variable is already set with the GSTREAMER_PATH

It looks like the orignal hook-cv2.py is not able to catch that I assume.

Based on the original hook-cv2.pym I did got some help with ChatGPT and it created for me that looks like it does the job by not failing on collecting modules, but I guess this is just a workaround for me and not the official way to do it:

#
# A minimal custom hook that forcibly grabs the cv2.pyd file
# from site-packages/cv2 without trying to load it (and thereby
# avoid the missing GStreamer DLL error).
#
# Adjust this to match your environment, e.g., if you have a
# different path or a different way of locating cv2.pyd.

import os
import glob
import site
from PyInstaller.utils.hooks import logger, collect_submodules, collect_data_files

hiddenimports = []
binaries = []
datas = []

try:
    # 1) Manually locate where cv2 is installed. For example:
    site_pkgs = site.getsitepackages()  # returns a list
    for sp in site_pkgs:
        cv2_dir = os.path.join(sp, 'cv2')
        if os.path.isdir(cv2_dir):
            # Collect all .pyd from the cv2 folder
            for pyd_file in glob.glob(os.path.join(cv2_dir, '*.pyd')):
                binaries.append((pyd_file, '.'))
            break
except Exception as e:
    logger.warning(f"Could not locate cv2.pyd manually: {e}")

# 2) If you want the python submodules (cv2.gapi, cv2.misc, etc.),
#    you can try collect_submodules. But it usually tries to import cv2.
#    So let's wrap it in a try/except so that if cv2 fails to import
#    due to missing GStreamer, it won't kill the build.

try:
    hiddenimports += collect_submodules('cv2', filter=lambda name: name != 'cv2.load_config_py2')
except ImportError:
    logger.warning("Skipping submodule collection because cv2 fails to import (likely missing GStreamer).")

# 3) If your build of OpenCV ships additional python files, collect them:
datas += collect_data_files(
    'cv2',
    include_py_files=True,
    includes=[
        'config.py',
        'config-3.py',
        f'config-{os.sys.version_info[0]}.{os.sys.version_info[1]}.py',
        'load_config_py3.py'
    ],
)

excludedimports = ['cv2.load_config_py2']

[rokm]

Regarding the Pyinstaller cv2 packaging, the PATH environment variable is already set with the GSTREAMER_PATH

Then it is a different DLL that fails to be resolved - for example, is the cv2 extension statically linked against OpenCV libraries? If not, is the path to OpenCV DLLs in PATH?

[timorkal]

It's only compiled statically with Gstreamer and via Mingw compiler.
The Mingwg dlls (libstdc++-6.dll, libgcc_s_seh-1.dll, etc...) are in the cv2 package itself, and the Gstreamer DLLs are in the GSTREAMER_PATH location.
And again, when I run my "main.py" inside my virtualenv or manually open a python shell and "import cv2" it works, so why then Pyinstaller is not be able to do the same?

[rokm]

And again, when I run my "main.py" inside my virtualenv or manually open a python shell and "import cv2" it works, so why then Pyinstaller is not be able to do the same?

Because PyInstaller has no way of imitating the os.add_dll_directory(GSTREAMER_PATH) call that you made in your main.py. If you sort out your environment in a way that will make import cv2 work in your main.py without adjusting DLL search path at the start of main.py, it should probably work with PyInstaller as well.

[timorkal]

so yes, I am using os.add_dll_directory(GSTREAMER_PATH) in my main.py.
but is there a way to make the Pyinstaller do the same, when running the hook-cv2.py or other way for such kind of implemntaion without overriding it's code with workaround hacks?

[rokm]

so yes, I am using os.add_dll_directory(GSTREAMER_PATH) in my main.py. but is there a way to make the Pyinstaller do the same, when running the hook-cv2.py or other way for such kind of implemntaion without overriding it's code with workaround hacks?

No.

[timorkal]

so yes, I am using os.add_dll_directory(GSTREAMER_PATH) in my main.py. but is there a way to make the Pyinstaller do the same, when running the hook-cv2.py or other way for such kind of implemntaion without overriding it's code with workaround hacks?

No.

Maybe I got it wrong, but Isn't this the place to ask for such thing?

[rokm]

Maybe I got it wrong, but Isn't this the place to ask for such thing?

It is, and I told you that there is no way to do what you're asking for without workaround hacks. (EDIT: other than sorting out your DLL search paths in environment, before running PyInstaller - as implied earlier).

We tend to cater to standard configurations, and have no way of covering all corner cases with custom builds and custom search paths.

[uxduck]

In this case, you could probably append/prepend the path in GSTREAMER_PATH to PATH environment variable before running PyInstaller, so that GStreamer DLLs can be discovered when cv2 extension is imported.

@rokm, I'm confused.

• Does that mean pyinstaller's opencv hook can't loads any DLLs? Adding dlls to PATH doesn't help python load them, only other DLLs? Python 3.8 requires us to use os.add_dll_directory()? Why doesn't the hook use os.add_dll_directory()?

Starting with Python 3.8, DLL’s search paths must be added with os.add_dll_directory since PATH is no longer used to resolve dependencies for imported extension modules - source

• What other way is there to allow cv2 to discover DLLs? Are you suggesting we need to statically link opencv to gstreamer?

---

The long detail

@rokm, I've got basically the same error and understand all your messages so far. It seems that updating PATH to include all the DLLs should be enough, but you're saying pyinstaller doesn't support DLLs?:

$env:Path = "C:\opencv\x64\vc17\bin;$env:Path"
$env:Path = "C:\gtk-build\gtk\x64\release\bin;$env:Path"
$env:Path = "C:\gtk-build\gtk\x64\release\lib\gstreamer-1.0;$env:Path"

I still get an error:

4312 INFO: Processing standard module hook 'hook-cv2.py' from 'C:\\Users\\admin\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\_pyinstaller_hooks_contrib\\stdhooks'
251 WARNING: Failed to collect submodules for 'cv2' because importing 'cv2' raised: ImportError: DLL load failed while importing cv2: The specified module could not be found

I've confirmed that these all the paths that are necessary, because this python script will succesfully import cv2. However, I must still use add_dll_directory:

import os
os.add_dll_directory("C:/opencv/x64/vc17/bin")
gtk_build_dir = "C:/gtk-build/gtk/x64/release"
gvsbuild_bin_dir = os.path.join(gtk_build_dir, "bin")
os.add_dll_directory(gvsbuild_bin_dir)

import cv2
print(cv2.getBuildInformation())

Note in python I do need to call os.add_dll_directory(), so I do that even for this opencv test script. I'm not sure how the hook can get away without it in https://github.com/pyinstaller/pyinstaller/blob/v6.12.0/PyInstaller/hooks/rthooks/pyi_rth_gstreamer.py:

---

I've built opencv, opencv_contrib and gvsbuild (all of gstreamer) locally, and have a project using gstreamer (without opencv) working file. I collect DLLs and typelibs, load DLLs (os.add_dll_directory) and also update the PATH (os.environ["PATH"]) to get this working nicely, even with pyinstaller (without the pyinstaller hooks).

However, I'm now trying to compile an exe with opencv with pyinstaller, and I can't get it to find the DLLs it needs.

it's dynamically linked (DLLs)

E.g. the opencv_gapi4120.dll and opencv_videoio4120.dll I built loads gstreamer-1.0-0.dll, gstapp-1.0-0.dll, etc.

cmake -G "Visual Studio 17 2022" -A x64 `
      -D CMAKE_INSTALL_PREFIX="C:/opencv" `
      -D BUILD_opencv_python3=ON `
      -D PYTHON3_EXECUTABLE="$env:PY311/python.exe" `
      -D PYTHON3_INCLUDE_DIR="$env:PY311/include" `
      -D PYTHON3_LIBRARY="$env:PY311/libs/python311.lib" `
      -D PYTHON3_PACKAGES_PATH="$env:PY311/Lib/site-packages" `
      -D WITH_GSTREAMER=ON `
      -D GSTREAMER_DIR="C:/gtk-build/gtk/x64/release" `
      -D WITH_FFMPEG=ON `
      -D OPENCV_ENABLE_NONFREE=ON `
      -D OPENCV_EXTRA_MODULES_PATH="../opencv_contrib/modules" `
      -S ../opencv -B .

[rokm]

In this case, you could probably append/prepend the path in GSTREAMER_PATH to PATH environment variable before running PyInstaller, so that GStreamer DLLs can be discovered when cv2 extension is imported.

@rokm, I'm confused.

• Does that mean pyinstaller's opencv hook can't loads any DLLs? Adding dlls to PATH doesn't help python load them, only other DLLs? Python 3.8 requires us to use os.add_dll_directory()? Why doesn't the hook use os.add_dll_directory()?

Because in general, the hook cannot guess what paths it should add to library search path via os.add_dll_directory().

To reframe your question: why does cv2/__init__.py not do that before it tries to import the extension, and requires you to externally set the library search path?

Starting with Python 3.8, DLL’s search paths must be added with os.add_dll_directory since PATH is no longer used to resolve dependencies for imported extension modules - source

Good point - I forgot that os.add_dll_directory replaced the PATH as library-search-modification mechanism and not augmented it.

• What other way is there to allow cv2 to discover DLLs? Are you suggesting we need to statically link opencv to gstreamer?

I don't think there really is a sane way; you could try creating a wrapper for PyInstaller that calls os.add_dll_directory() for all required paths before calling PyInstaller's main() function. Or you can try adding the os.add_dll_directory() calls to your local copy of the hook just to see if it gets you any further.

Note, however, that collect_submodule spawns a python sub-process, so the modification made in the top-level PyInstaller process might not have any effect there. Same goes for the import of packages that happens prior to binary dependency analysis...

[uxduck]

Ahh, thanks, I appreciate your reply!

I had already tried editing the local cv2 hook but failed. So the subprocess is probably the reason that didn't work.

Solution

I still benefit from using the hook for preparing other files (thank you!), but just need to ignore that warning. Finally, I solved it with (among existing code that copies binaries into the frozen bundle, uses os.add_dll_directory):

os.environ["GST_PLUGIN_PATH"] = str(gstreamer_bin_directory)

This was not something I needed for gstreamer in python (Pygobject), but only for OpenCV to find gstreamer elements.

Note

I needed to also replace the following code generated in dist\Appname\_internal\cv2\config-3.11.py:

diff --git a/./config-3.11-old.py b/./config-3.11.py
index f3f0aa1..42a43cc 100644
--- a/./config-3.11-old.py
+++ b/./config-3.11.py
@@ -1,3 +1,3 @@
 PYTHON_EXTENSIONS_PATHS = [
-    os.path.join('C:/Users/admin/AppData/Local/Programs/Python/Python311/Lib/site-packages/cv2', 'python-3.11')
-] + PYTHON_EXTENSIONS_PATHS
+    os.path.join(LOADER_DIR, 'python-3.11')
+] + PYTHON_EXTENSIONS_PATHS
\ No newline at end of file

And unnecessary, but just tidying up, by emptying this file dist\Fe\_internal\cv2\config.py

import os

BINARIES_PATHS = [
    os.path.join('C:/opencv', 'x64/vc17/bin')
] + BINARIES_PATHS