Python Linking Issues¶

The Rust gateway links to Python through pyo3. Most runtime failures in this area are caused by the gateway being built against one interpreter and run with another, or by the Python shared library not being visible at runtime.

Build Rule¶

Always build the gateway with the same interpreter you expect at runtime:

PYO3_PYTHON="$(pwd)/venvs/flexserv/bin/python" \
  cargo build --manifest-path flexserv/gateway/Cargo.toml

macOS¶

Typical failure:

missing Python.framework at runtime
missing libiconv

run-local.sh already exports a macOS-friendly DYLD_LIBRARY_PATH.

If you run the gateway manually, export it yourself for your installed Python version:

export DYLD_LIBRARY_PATH="/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13/lib:/opt/homebrew/opt/libiconv/lib:${DYLD_LIBRARY_PATH:-}"

Then run the gateway.

Linux / Docker¶

The Dockerfiles explicitly register the uv-managed Python shared library path with ldconfig. If you run outside those images and see missing libpython3*.so.1.0, expose that directory through LD_LIBRARY_PATH.

Example pattern:

export LD_LIBRARY_PATH="/path/to/python/lib:${LD_LIBRARY_PATH:-}"

Quick Checks¶

Confirm the interpreter used for build:

echo "$PYO3_PYTHON"

Confirm the runtime interpreter:

./venvs/flexserv/bin/python -c 'import sys; print(sys.executable)'

If the build and runtime interpreters do not match, rebuild the gateway.