FAQ

ModuleNotFoundError: unable to find fdb5

raise ModuleNotFoundError(
ModuleNotFoundError: unable to find fdb5

PyFDB uses findlibs to locate libfdb5 at import time. This error means findlibs exhausted all of its search paths without finding the library.

Set FDB5_HOME to the root of your FDB installation (the directory that contains a lib/ subdirectory with libfdb5.so / libfdb5.dylib):

export FDB5_HOME=<path-to-fdb-install-or-build>

For a local stack build this is the build directory:

export FDB5_HOME=<path-to-stack>/build

If you are on a system where libfdb5 is installed via a package manager or module system and findlibs still cannot find it, also set:

export FINDLIBS_DISABLE_PACKAGE=yes   # prevent stale conda/pip shadowing

You can verify what findlibs resolves after setting the variable:

python -m pyfdb --print-home

See Development Setup for the full environment variable reference.

RuntimeError: Cannot find the ecCodes library

raise RuntimeError("Cannot find the ecCodes library")
RuntimeError: Cannot find the ecCodes library

This error is raised by the eccodes Python package when it cannot locate libeccodes at import time. Set ECCODES_HOME to the root of your ecCodes installation (the directory that contains a lib/ subdirectory with libeccodes.so / libeccodes.dylib):

export ECCODES_HOME=<path-to-eccodes-install-or-build>

For a local stack build where ecCodes was compiled as part of the bundle, this is the same build directory as FDB5_HOME:

export ECCODES_HOME=<path-to-stack>/build

See Development Setup for the full environment variable reference.

pytest aborts immediately (abort / signal 6)

$ pytest
[1]    50372 abort      pytest

A hard abort at collection time — before any test output — usually means a shared library was loaded twice or in an incompatible combination, causing an assertion failure or fatal error deep inside the C++ runtime.

The most common cause when working with a local build is that findlibs picks up a libfdb5 (or one of its dependencies) that was installed as a Python package (e.g. via pip install fdb5lib) instead of the locally built one. Two different versions of the same library loaded in the same process will corrupt each other’s state.

Fix: disable package-based search and point directly at the local build:

export FINDLIBS_DISABLE_PACKAGE=yes
export FDB5_HOME=<path-to-stack>/build
export ECCODES_HOME=<path-to-stack>/build

Then run pytest again. Use --print-home-deps to confirm which libraries are resolved before running the suite:

python -m pyfdb --print-home-deps

See Development Setup for the full environment variable reference. Tests fail after switching Python versions ——————————————

The pyfdb_bindings extension is compiled against a specific Python version and ABI. The CMake wheel build records the target Python at configure time and does not automatically recompile when the active interpreter changes. If you switch Python versions (e.g. from 3.11 to 3.13) after an initial build, the compiled .so carries the old ABI tag and importing it with the new interpreter will fail with errors such as:

ImportError: <path>/pyfdb_bindings.cpython-311-...so: cannot open shared object file

or produce silent test failures caused by an ABI mismatch.

Fix: do a full rebuild from a clean build directory. Delete the existing build folder and re-run CMake with the new interpreter active in your venv:

rm -rf <path-to-stack>/build
mkdir <path-to-stack>/build && cd <path-to-stack>/build

uv venv --python 3.13   # or whichever version you now want
source ../.venv/bin/activate
uv pip install build setuptools wheel pybind11 findlibs PyYAML pytest eccodes

cmake .. -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DENABLE_PYTHON_FDB_INTERFACE=ON -DENABLE_FDB_DOCUMENTATION=OFF -DENABLE_MEMFS=ON
ninja

Then reinstall the editable package from the freshly built staging area:

uv pip install -e <path-to-stack>/build/pyfdb-python-package-staging