FAISS

1.13.2 verified Mon May 11 auth: no python install: verified quickstart: verified

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.

pip install faiss-cpu

Common errors

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). ↓

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.

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.

error AttributeError: module 'faiss' has no attribute 'IndexFlatL2' ↓

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.

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.

error AttributeError: module 'faiss' has no attribute 'StandardGpuResources' ↓

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.

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.

error RuntimeError: Error: 'nx >= k' failed: Number of training points (...) should be at least as large as number of clusters (...). ↓

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.

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.

error Failed to build wheel for faiss-cpu ↓

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).

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).

Warnings

breaking 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+. ↓

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.

breaking 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. ↓

fix Build and load indices on the same architecture. Do not ship pre-built indices across architectures. Regenerate indices on the target platform.

breaking 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. ↓

fix Set FAISS_OPT_LEVEL=generic environment variable to force the generic (non-SIMD) extension in containers where AVX2 misdetection occurs.

breaking 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. ↓

fix Always call .astype('float32') on vectors before passing to index.add() or index.search(). Ensure contiguous memory: np.ascontiguousarray(v.astype('float32')).

gotcha 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

Install

conda install -c pytorch -c conda-forge faiss-cpu=1.13.2

conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.13.2

Install compatibility verified last tested: 2026-05-11

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.90s 175.5M

3.10 slim (glibc) - - 0.69s 169M

3.11 alpine (musl) - - 1.77s 184.2M

3.11 slim (glibc) - - 1.74s 177M

3.12 alpine (musl) - - 1.27s 172.5M

3.12 slim (glibc) - - 1.32s 165M

3.13 alpine (musl) - - 1.01s 171.8M

3.13 slim (glibc) - - 1.28s 165M

3.9 alpine (musl) - - 0.74s 182.6M

3.9 slim (glibc) - - 0.77s 178M

Imports

faiss
wrong
```
import faiss_cpu
```
correct
```
import faiss
```
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)
wrong
```
pip install faiss-gpu
```
correct
```
conda install -c pytorch -c nvidia 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.

Quickstart verified last tested: 2026-05-11

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')