{"id":19,"library":"faiss-cpu","title":"FAISS","description":"Facebook AI Research Similarity Search. C++ library with Python bindings for efficient similarity search and clustering of dense vectors. Supports flat (exact), IVF (approximate), HNSW, PQ, and many other index types. CPU-only via PyPI (faiss-cpu); GPU support requires conda or building from source. Officially maintained by Meta/Facebook AI Research; PyPI wheel builds maintained by the community (faiss-wheels project). Import is always 'import faiss' regardless of which package is installed.","status":"active","version":"1.13.2","language":"python","source_language":"en","source_url":"https://github.com/facebookresearch/faiss","tags":["faiss","vector-search","similarity-search","embeddings","ann","hnsw","ivf","offline","library"],"install":[{"cmd":"pip install faiss-cpu","lang":"bash","label":"CPU-only (PyPI, recommended)"},{"cmd":"conda install -c pytorch -c conda-forge faiss-cpu=1.13.2","lang":"bash","label":"CPU via conda (official channel)"},{"cmd":"conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.13.2","lang":"bash","label":"GPU via conda (CUDA, official channel)"}],"dependencies":[{"reason":"Required. All vectors are passed as numpy float32 arrays. Passing Python lists or wrong dtype raises C++-level errors.","package":"numpy","optional":false}],"imports":[{"note":"Package is installed as faiss-cpu but imported as faiss. This is always correct regardless of whether faiss-cpu, faiss-gpu, or conda faiss is installed.","wrong":"import faiss_cpu","symbol":"faiss","correct":"import faiss"},{"note":"faiss-gpu on PyPI is frozen at 1.7.2 (2021), supports only Python <= 3.10, and is not maintained. GPU support via pip is discontinued as of 1.7.3. Use conda for GPU.","wrong":"pip install faiss-gpu","symbol":"faiss-gpu (PyPI, discontinued)","correct":"conda install -c pytorch -c nvidia faiss-gpu"}],"quickstart":{"code":"import faiss\nimport numpy as np\n\ndim = 128\nn_vectors = 10000\n\n# All vectors MUST be float32\nvectors = np.random.random((n_vectors, dim)).astype('float32')\n\n# Flat (exact) index\nindex = faiss.IndexFlatL2(dim)\nprint(index.is_trained)  # True (flat indices don't need training)\n\nindex.add(vectors)\nprint(index.ntotal)  # 10000\n\n# Search: returns (distances, indices)\nquery = np.random.random((5, dim)).astype('float32')\nD, I = index.search(query, k=10)\nprint(I.shape)  # (5, 10)\n\n# Save/load index\nfaiss.write_index(index, 'my_index.faiss')\nindex2 = faiss.read_index('my_index.faiss')","lang":"python","description":"Vectors must be float32 numpy arrays. IndexFlatL2 is exact (no training). Approximate indices (IVF, HNSW) require index.train(vectors) before index.add()."},"warnings":[{"fix":"Use conda for GPU: conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.13.2. For cuVS-accelerated GPU: conda install faiss-gpu-cuvs.","message":"faiss-gpu on PyPI is frozen at 1.7.2 (2021) and discontinued. pip install faiss-gpu installs a 3-year-old build supporting only Python <= 3.10 and CUDA 11. Will not import on Python 3.11+.","severity":"breaking","affected_versions":"all PyPI faiss-gpu"},{"fix":"Build and load indices on the same architecture. Do not ship pre-built indices across architectures. Regenerate indices on the target platform.","message":"FAISS indices saved in one architecture (e.g., x86_64) are not always loadable in another (e.g., arm64). Cross-platform index portability is not guaranteed. Loading an incompatible index raises a segfault or corrupted data error.","severity":"breaking","affected_versions":"all"},{"fix":"Set FAISS_OPT_LEVEL=generic environment variable to force the generic (non-SIMD) extension in containers where AVX2 misdetection occurs.","message":"Indices built with the AVX2 SIMD extension are not compatible with the generic extension. faiss-cpu PyPI wheels include both generic and AVX2 variants and select at runtime. In containers where CPU features are misdetected, this causes segfaults or wrong results.","severity":"breaking","affected_versions":"all"},{"fix":"Always call .astype('float32') on vectors before passing to index.add() or index.search(). Ensure contiguous memory: np.ascontiguousarray(v.astype('float32')).","message":"All vectors passed to FAISS must be numpy float32 (dtype='float32'). Passing float64, int, or Python lists causes TypeError at the C++ binding layer or silent wrong results.","severity":"breaking","affected_versions":"all"},{"fix":"Check index.is_trained before calling add(). For IVF indices, call index.train(training_vectors) first. Training vectors should be representative of the full dataset.","message":"Approximate indices (IndexIVFFlat, IndexIVFPQ, IndexHNSW variants) require index.train(vectors) before index.add(). Calling add() on an untrained IVF index raises a 'not trained' assertion error. IndexFlat* are the only types that are pre-trained.","severity":"gotcha","affected_versions":"all"},{"fix":"Call faiss.write_index(index, path) after building or modifying indices. For production, wrap in a persistence layer or use a dedicated vector database that uses FAISS internally.","message":"FAISS is a library, not a database. It has no persistence by default. Indices exist only in memory. faiss.write_index() / faiss.read_index() must be called explicitly to save/load. There is no automatic recovery on crash.","severity":"gotcha","affected_versions":"all"},{"fix":"For large-scale search, use approximate indices: IndexIVFFlat (IVF with flat quantizer), IndexHNSWFlat (graph-based), or IndexIVFPQ (compressed). Tune nlist, nprobe, and M parameters for the accuracy/speed tradeoff needed.","message":"faiss.IndexFlatL2 performs exact exhaustive search — O(n) per query. For large datasets (>100k vectors), query time is prohibitively slow. Many tutorials use IndexFlatL2 for simplicity without noting this.","severity":"gotcha","affected_versions":"all"},{"fix":"Use pre-built wheels: specify a supported Python/platform combination (CPython 3.10+ on Linux x86_64/ARM64, macOS ARM64/x86_64, Windows x86_64). For unsupported combinations, use conda which has broader binary support.","message":"pip install faiss-cpu from source (not wheel) requires SWIG, CMake, and a BLAS library to be present on the system. Occurs when no pre-built wheel is available for the Python/OS/arch combination. Fails with 'swig not found' or BLAS linking errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-11T19:02:52.297Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Ensure `faiss-cpu` is installed correctly for your environment using `pip install faiss-cpu` (or `conda install faiss-cpu -c pytorch` if using Conda). If the error persists, verify Python version compatibility, as newer Python versions may require specific `faiss-cpu` builds or building from source.","cause":"The `faiss` library is not correctly installed in the current Python environment, or there are compatibility issues with the Python version or underlying system libraries. This generic error often appears when a higher-level library attempts to import Faiss.","error":"ImportError: 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)."},{"fix":"First, check for any local files named `faiss.py` or a folder named `faiss` in your project directory and rename them to avoid shadowing the installed library. If no such files exist, try a forced reinstallation with `pip install --force-reinstall faiss-cpu` to ensure all components are properly installed.","cause":"This error occurs when the `faiss` module is imported, but fundamental classes like `IndexFlatL2` are not found. This can be caused by a corrupted or incomplete `faiss` installation, a name collision with a local `faiss.py` file, or attempting to use a Faiss index type that might be associated with a GPU build while only `faiss-cpu` is installed.","error":"AttributeError: module 'faiss' has no attribute 'IndexFlatL2'"},{"fix":"If you intend to use GPU features, you must install the `faiss-gpu` package, ensuring compatibility with your CUDA toolkit version (e.g., `pip install faiss-gpu-cu12`). If you only want CPU functionality, remove any code that references `StandardGpuResources` or other GPU-specific Faiss objects.","cause":"This error indicates that you are attempting to use GPU-specific Faiss functionalities, such as `StandardGpuResources`, but only the CPU-only version (`faiss-cpu`) is installed or the GPU version is not correctly detected/initialized.","error":"AttributeError: module 'faiss' has no attribute 'StandardGpuResources'"},{"fix":"Increase the number of training vectors passed to `index.train()` so that it is greater than or equal to `nlist` (the number of clusters/centroids you specified when creating the index). Alternatively, reduce the `nlist` parameter if your dataset is inherently small.","cause":"This runtime error occurs during the training phase of a Faiss index (most commonly with IVF indexes), when the number of provided training vectors (`nx`) is less than the specified number of clusters (`k`, often referred to as `nlist`). Faiss requires sufficient data points to form the requested number of clusters.","error":"RuntimeError: Error: 'nx >= k' failed: Number of training points (...) should be at least as large as number of clusters (...)."},{"fix":"Ensure all necessary build tools are installed: on Windows, this includes Visual C++ build tools and SWIG; on Linux, `libblas-dev`, `liblapack-dev`, and `swig`. For specific Python versions, especially newer ones like 3.12, check for pre-built wheels on PyPI or consider using Conda, which often provides more stable binaries. Alternatively, downgrade your Python version to one known to be compatible with existing `faiss-cpu` wheels (e.g., 3.10 or 3.11).","cause":"This installation error, often accompanied by messages like 'ModuleNotFoundError: No module named 'swig'' or issues with `cl.exe`, means that the `faiss-cpu` wheel could not be built from source during `pip install`. This usually indicates missing build dependencies (like SWIG on Windows or a C++ compiler) or incompatibility with newer Python versions (e.g., Python 3.12).","error":"Failed to build wheel for faiss-cpu"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-11","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.9,"mem_mb":11.2,"disk_size":"175.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":11.2,"disk_size":"169M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.77,"mem_mb":12.3,"disk_size":"184.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.74,"mem_mb":12.3,"disk_size":"177M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.27,"mem_mb":12.1,"disk_size":"172.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.32,"mem_mb":12.1,"disk_size":"165M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.01,"mem_mb":12.9,"disk_size":"171.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":12.9,"disk_size":"165M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":11,"disk_size":"182.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":11,"disk_size":"178M"}]},"quickstart_checks":{"last_tested":"2026-05-11","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}