Heuristic:Neuml Txtai MacOS OpenMP Workaround
| Knowledge Sources | |
|---|---|
| Domains | Troubleshooting, Platform_Compatibility, Faiss |
| Last Updated | 2026-02-09 17:00 GMT |
Overview
Platform-specific workaround that automatically sets `OMP_NUM_THREADS=1` and `KMP_DUPLICATE_LIB_OK=TRUE` on macOS and Windows to prevent Faiss segmentation faults and OpenMP errors.
Description
Faiss uses OpenMP for parallel vector operations, but on macOS and Windows, conflicting OpenMP library versions can cause segmentation faults or the infamous "OMP: Error #15: Initializing libiomp5" crash. txtai automatically detects Darwin (macOS) and Windows (`os.name == "nt"`) at import time and sets two environment variables as workarounds: `OMP_NUM_THREADS=1` restricts OpenMP to single-threaded mode (preventing the segfault), and `KMP_DUPLICATE_LIB_OK=TRUE` suppresses the duplicate library error. These are set only if the user has not already defined them, respecting custom configurations.
Usage
This heuristic applies automatically at import time when using Faiss on macOS or Windows. If you experience crashes related to OpenMP even after the automatic fix, you can also set these environment variables explicitly. Additional macOS-specific environment variables include `PYTORCH_MPS_DISABLE=1` (to disable MPS) and `LLAMA_NO_METAL=1` (to disable Metal in llama.cpp).
The Insight (Rule of Thumb)
- Action 1: Export `OMP_NUM_THREADS=1` before running txtai on macOS or Windows (done automatically by txtai).
- Action 2: Export `KMP_DUPLICATE_LIB_OK=TRUE` to suppress OMP Error #15 (done automatically).
- Action 3: Export `PYTORCH_MPS_DISABLE=1` if MPS causes instability on Apple Silicon.
- Action 4: Export `LLAMA_NO_METAL=1` if llama.cpp Metal acceleration causes issues.
- Trade-off: `OMP_NUM_THREADS=1` disables Faiss multi-threading, which may reduce Faiss search speed on multi-core systems. The stability gain outweighs the performance cost in most use cases.
Reasoning
macOS ships with its own copy of libomp (via Accelerate framework), while PyTorch and Faiss may each bring their own OpenMP runtime. When multiple OpenMP libraries are loaded in the same process, the runtime state conflicts, causing segmentation faults or initialization errors. Restricting to a single thread avoids triggering the conflicting parallel initialization. The `KMP_DUPLICATE_LIB_OK` flag is an Intel-specific workaround that tells the Intel OpenMP runtime to tolerate duplicate library loads rather than aborting. This is a well-documented issue in the Faiss and PyTorch communities. txtai applies these workarounds defensively, only setting them if the user has not already provided custom values.
# From src/python/txtai/ann/dense/faiss.py:10-15
if platform.system() == "Darwin" or os.name == "nt":
# Workaround for a Faiss issue causing segmentation faults. See txtai FAQ for more.
os.environ["OMP_NUM_THREADS"] = os.environ.get("OMP_NUM_THREADS", "1")
# Workaround for a Faiss issue with OMP: Error #15. See txtai FAQ for more.
os.environ["KMP_DUPLICATE_LIB_OK"] = os.environ.get("KMP_DUPLICATE_LIB_OK", "TRUE")