Code beginner · 3 min read

How to use FAISS in Python

Q: How to use FAISS in Python

Use the faiss Python library to create an index, add vectors, and perform similarity search efficiently with methods like IndexFlatL2 and search.

Direct answer

Use the faiss Python library to create an index, add vectors, and perform similarity search efficiently with methods like IndexFlatL2 and search.

Setup

Install

bash

pip install faiss-cpu

Imports

python

import numpy as np
import faiss

Examples

inAdd 5 random 128-d vectors and search top 3 nearest neighbors for a query vector.

outDistances and indices of the 3 nearest neighbors printed as numpy arrays.

inCreate an index for 512-d vectors, add 1000 vectors, and query top 5 neighbors.

outArrays showing distances and indices of the 5 closest vectors returned.

inSearch in an empty index.

outReturns empty arrays or raises an error depending on implementation.

Integration steps

Install the FAISS Python package with pip.
Import faiss and numpy in your Python script.
Create a FAISS index suitable for your vector dimension (e.g., IndexFlatL2 for L2 distance).
Add your numpy array of vectors to the index using index.add().
Query the index with index.search() to find nearest neighbors.
Process the returned distances and indices for your application.

Full code

python

import numpy as np
import faiss

# Dimension of vectors
vector_dim = 128

# Create a FAISS index for L2 distance
index = faiss.IndexFlatL2(vector_dim)

# Generate some random vectors (e.g., 5 vectors)
vectors = np.random.random((5, vector_dim)).astype('float32')

# Add vectors to the index
index.add(vectors)

# Create a query vector
query_vector = np.random.random((1, vector_dim)).astype('float32')

# Search for the 3 nearest neighbors
k = 3
distances, indices = index.search(query_vector, k)

print("Query vector:\n", query_vector)
print(f"Top {k} nearest neighbors' distances:\n", distances)
print(f"Top {k} nearest neighbors' indices:\n", indices)

API trace

Request

json

{"index_type": "IndexFlatL2", "add_vectors": [[...]], "search_query": [[...]], "k": 3}

Response

json

{"distances": [[float]], "indices": [[int]]}

Extractdistances, indices = index.search(query_vector, k)

Variants

Using IVF (Inverted File) Index for Large Datasets ›

Use IVF index when working with large datasets to reduce search time with approximate nearest neighbor search.

python

import numpy as np
import faiss

vector_dim = 128
nlist = 10  # number of clusters
quantizer = faiss.IndexFlatL2(vector_dim)  # quantizer for IVF
index = faiss.IndexIVFFlat(quantizer, vector_dim, nlist, faiss.METRIC_L2)

# Train the index with training vectors
train_vectors = np.random.random((1000, vector_dim)).astype('float32')
index.train(train_vectors)

# Add vectors to the index
index.add(train_vectors)

# Query
query_vector = np.random.random((1, vector_dim)).astype('float32')
k = 5
index.nprobe = 5  # number of clusters to search
distances, indices = index.search(query_vector, k)

print("Distances:", distances)
print("Indices:", indices)

GPU-Accelerated FAISS Index ›

Use GPU index to accelerate search speed on machines with compatible GPUs.

python

import numpy as np
import faiss

vector_dim = 128
index_cpu = faiss.IndexFlatL2(vector_dim)

# Move index to GPU
res = faiss.StandardGpuResources()
index_gpu = faiss.index_cpu_to_gpu(res, 0, index_cpu)

vectors = np.random.random((100, vector_dim)).astype('float32')
index_gpu.add(vectors)

query_vector = np.random.random((1, vector_dim)).astype('float32')
k = 3
distances, indices = index_gpu.search(query_vector, k)

print("GPU Distances:", distances)
print("GPU Indices:", indices)

Cosine Similarity Search with FAISS ›

Use inner product index with normalized vectors to perform cosine similarity search.

python

import numpy as np
import faiss

vector_dim = 128

# Normalize vectors for cosine similarity
vectors = np.random.random((10, vector_dim)).astype('float32')
faiss.normalize_L2(vectors)

index = faiss.IndexFlatIP(vector_dim)  # Inner product for cosine similarity
index.add(vectors)

query_vector = np.random.random((1, vector_dim)).astype('float32')
faiss.normalize_L2(query_vector)

k = 3
distances, indices = index.search(query_vector, k)

print("Cosine similarity scores:", distances)
print("Indices:", indices)

Performance

Latency~10-50ms for 1000 vectors on CPU with IndexFlatL2

CostFAISS is open-source and free; cost depends on your compute resources.

Rate limitsNo API rate limits; local library usage only.

Use approximate indexes like IVF to reduce search latency on large datasets.
Normalize vectors once if using cosine similarity to avoid repeated computation.
Batch queries to amortize overhead when searching multiple vectors.

Approach	Latency	Cost/call	Best for
IndexFlatL2 (CPU)	~10-50ms	Free (local)	Small to medium datasets, exact search
IndexIVFFlat (CPU)	~5-20ms	Free (local)	Large datasets, approximate search
GPU IndexFlatL2	~1-10ms	Free (local, requires GPU)	High throughput, low latency search
IndexFlatIP + normalization	~10-50ms	Free (local)	Cosine similarity search

✓

Quick tip

Always ensure your vectors are float32 numpy arrays before adding them to a FAISS index to avoid type errors.

⚠

Common mistake

Forgetting to train an IVF index before adding vectors causes runtime errors or incorrect search results.

Verified 2026-04

Verify ↗