FAISS

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

• pip install faiss-cpu CPU-only (PyPI, recommended)
• conda install -c pytorch -c conda-forge faiss-cpu=1.13.2 CPU via conda (official channel)
• conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.13.2 GPU via conda (CUDA, official channel)

Imports

• faiss

  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)

  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

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