faiss on macOS (ARM) causes Python 3.12 error, resolved by switching to Python 3.11

[katherineh123]

Running the project on Ubuntu 24.04.2 LTS (virtual machine hosted on Mac) resulted in a Python 3.12 compatibility error related to faiss. Switching the environment to Python 3.11 resolved the issue.

Workaround
In the Dockerfile, change ARG PYTHON_VERSION=3.12 to 3.11

To reproduce:
Run the project following the ReadMe, on an Ubuntu 24.04.2 LTS virtual machine using Python 3.12. (The Dockerfile uses PYTHON_VERSION=3.12 by default. The faiss-cpu version in this project is 1.9.0, set in pyproject.toml. Switching to faiss-cpu v 1.11.0 did not resolve the issue).

Error log:
Error: Could not import faiss python package. Please install it with pip install faiss-gpu (for CUDA supported GPU) or pip install faiss-cpu (depending on Python version).
Traceback (most recent call last):
File "/workspace/.venv/lib/python3.12/site-packages/langchain_community/vectorstores/faiss.py", line 56, in dependable_faiss_import
import faiss
File "/workspace/.venv/lib/python3.12/site-packages/faiss/init.py", line 16, in
from .loader import *
File "/workspace/.venv/lib/python3.12/site-packages/faiss/loader.py", line 88, in
instruction_sets = supported_instruction_sets()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/workspace/.venv/lib/python3.12/site-packages/faiss/loader.py", line 53, in supported_instruction_sets
if is_sve_supported():
^^^^^^^^^^^^^^^^^^
File "/workspace/.venv/lib/python3.12/site-packages/faiss/loader.py", line 43, in is_sve_supported
import numpy.distutils.cpuinfo
ModuleNotFoundError: No module named 'numpy.distutils'

[onestardao]

this is basically Problem No.6 in our Problem Map — environment / dependency mismatch during deployment bootstrap.
FAISS on Python 3.12 is tripping over ABI & package compatibility, which is why downgrading to 3.11 “fixes” it.
our fix approach locks the runtime, enforces deterministic dependency resolution, and runs pre-ingestion checks so you never hit this mid-run.

MIT-licensed, open-source — let me know if you want the full 16-problem list with fixes.