Install & Compatibility
Where this runs
tested against v1.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.677s · 175.7MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 4.5s · import 0.662s · 169MB
174MB installed
● package 174MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
faiss
✓ import faiss
✗ import faiss_cpu
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.
faiss-gpu (PyPI, discontinued)
✓ conda install -c pytorch -c nvidia faiss-gpu
✗ pip install faiss-gpu
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.
Vectors must be float32 numpy arrays. IndexFlatL2 is exact (no training). Approximate indices (IVF, HNSW) require index.train(vectors) before index.add().
import faiss
import numpy as np
dim = 128
n_vectors = 10000
# All vectors MUST be float32
vectors = np.random.random((n_vectors, dim)).astype('float32')
# Flat (exact) index
index = faiss.IndexFlatL2(dim)
print(index.is_trained) # True (flat indices don't need training)
index.add(vectors)
print(index.ntotal) # 10000
# Search: returns (distances, indices)
query = np.random.random((5, dim)).astype('float32')
D, I = index.search(query, k=10)
print(I.shape) # (5, 10)
# Save/load index
faiss.write_index(index, 'my_index.faiss')
index2 = faiss.read_index('my_index.faiss')
Debug
Known issues
breakingfaiss-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+.fixUse 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.
affects: all PyPI faiss-gpu
breakingFAISS 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.fixBuild and load indices on the same architecture. Do not ship pre-built indices across architectures. Regenerate indices on the target platform.
affects: all
breakingIndices 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.fixSet FAISS_OPT_LEVEL=generic environment variable to force the generic (non-SIMD) extension in containers where AVX2 misdetection occurs.
affects: all
breakingAll 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.fixAlways call .astype('float32') on vectors before passing to index.add() or index.search(). Ensure contiguous memory: np.ascontiguousarray(v.astype('float32')). affects: all
gotchaApproximate 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.fixCheck index.is_trained before calling add(). For IVF indices, call index.train(training_vectors) first. Training vectors should be representative of the full dataset.
affects: all
gotchaFAISS 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.fixCall 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.
affects: all
gotchafaiss.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.fixFor 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.
affects: all
gotchapip 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.fixUse 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.
affects: all
Errors
Common errors & fixes
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).
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.
fixEnsure `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.
AttributeError: module 'faiss' has no attribute 'IndexFlatL2'
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.
fixFirst, 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.
AttributeError: module 'faiss' has no attribute 'StandardGpuResources'
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.
fixIf 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.
RuntimeError: Error: 'nx >= k' failed: Number of training points (...) should be at least as large as number of clusters (...).
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.
fixIncrease 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.
Failed to build wheel for faiss-cpu
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).
fixEnsure 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).
Upgrade
Version history
1.15.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
numpyrequiredRequired. All vectors are passed as numpy float32 arrays. Passing Python lists or wrong dtype raises C++-level errors.