Registry / vector-search / faiss-gpu

faiss-gpu

JSON →
library1.14.3pypiunverified

Faiss GPU (Facebook AI Similarity Search) is a library for efficient similarity search and clustering of dense vectors, with a strong focus on high performance through GPU acceleration. The `faiss-gpu` package on PyPI provides Python bindings designed for NVIDIA GPUs. While the upstream Faiss library and its associated wheel-building projects have progressed to significantly newer versions (e.g., v1.9.x or v1.13.x), the current version of `faiss-gpu` directly available on PyPI is `1.7.2` (as of early 2022). This implies that many recent features, bug fixes, and performance improvements from more current Faiss releases are not present in the PyPI `faiss-gpu` package.

pip install faiss-gpu
INSTALL
IMPORT
SIG · FAISS-GPU
F
faiss-gpu
vector-searchenv1.14.3
Install
9.7s avg
Import
530ms
Disk
170MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.7.2 · 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
musl
glibc
py 3.10
✕ build_error
✓ 13.85s
py 3.11
✕ build_error
1/2 runs
py 3.12
✕ build_error
1/2 runs
py 3.13
✕ build_error
1/2 runs
py 3.9
✕ build_error
✓ 5.55s
170MB installed
● package 170MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

faiss
import faiss
import faiss_gpu
The Python package name is `faiss-gpu`, but the module is imported as `faiss`. GPU-specific classes like `GpuIndexFlatL2` are then accessed through the `faiss` module.

This quickstart demonstrates how to initialize a GPU-accelerated Faiss index, add vectors to it, and perform a similarity search. It uses `faiss.StandardGpuResources` to manage GPU memory and `faiss.GpuIndexFlatL2` for a basic brute-force L2 distance search. Ensure your system has a compatible NVIDIA GPU and CUDA toolkit installed.

import faiss import numpy as np # Check for GPU availability if not faiss.get_num_gpus(): print("Warning: No GPUs detected. Faiss GPU functionality will not be available.") print("Ensure NVIDIA drivers and CUDA toolkit are correctly installed.") # In a real application, you might exit or switch to faiss-cpu here. # For this quickstart, we will proceed assuming GPU context is desired if available. # Define parameters d = 128 # vector dimension nb = 100000 # database size nq = 1000 # number of query vectors k = 4 # number of nearest neighbors to search for # Generate random data np.random.seed(1234) xb = np.random.random((nb, d)).astype('float32') xb[:, 0] += np.arange(nb) / 1000. xq = np.random.random((nq, d)).astype('float32') xq[:, 0] += np.arange(nq) / 1000. print(f"Database vectors shape: {xb.shape}") print(f"Query vectors shape: {xq.shape}") # Initialize GPU resources # A single StandardGpuResources object handles memory management on a specific GPU. res = faiss.StandardGpuResources() # Create a GPU index (e.g., IndexFlatL2 for brute-force L2 distance) # 'res' links the index to the GPU resources, 'd' is the vector dimension. index_flat = faiss.GpuIndexFlatL2(res, d) # Add vectors to the index print("Adding vectors to GPU index...") index_flat.add(xb) print(f"Number of vectors in the index: {index_flat.ntotal}") # Search for nearest neighbors print(f"Searching for {k} nearest neighbors for {nq} queries...") D, I = index_flat.search(xq, k) # D: distances, I: indices print("\nFirst 5 query results (indices of nearest neighbors):") print(I[:5]) print("\nFirst 5 query results (distances):") print(D[:5])
Debug
Known issues
breakingThe `faiss-gpu` PyPI package (v1.7.2, released early 2022) is significantly outdated compared to the upstream Faiss library (latest official v1.9.1; `faiss-wheels` targets v1.13.x). This means many new features, bug fixes, and performance optimizations from more recent Faiss versions will not be available, and API signatures may differ from current documentation. For newer Faiss versions with GPU support, users often need to compile from source or seek alternative, potentially unofficial, wheel distributions.
fix
For the latest Faiss features, consider compiling Faiss from source (from `facebookresearch/faiss`) with GPU support. If a newer `faiss-gpu` PyPI package eventually becomes available, upgrade to it. Alternatively, `faiss-cpu` offers a more up-to-date PyPI presence for CPU-only workflows.
affects: 1.7.2 and older on PyPI
gotchaUsing `faiss-gpu` requires a properly installed NVIDIA CUDA toolkit, compatible NVIDIA drivers, and potentially cuBLAS/cuDNN libraries. The Faiss build is linked against specific CUDA versions. Missing or incompatible GPU dependencies will lead to runtime errors (e.g., `FaissError` during index creation or `ModuleNotFoundError` if GPU-specific components cannot load).
fix
Refer to the Faiss installation guides and your NVIDIA CUDA documentation for your specific OS and hardware. Ensure `nvcc --version` shows a compatible CUDA toolkit. On Linux, ensure `LD_LIBRARY_PATH` (or equivalent) correctly points to your CUDA library directories.
affects: All `faiss-gpu` versions
gotchaWhile the PyPI package name is `faiss-gpu`, the Python module is imported as `faiss`. Attempting `import faiss_gpu` will result in an `ImportError`. GPU-specific functionality is then accessed through methods and classes within the `faiss` module (e.g., `faiss.GpuIndexFlatL2`).
fix
Always use `import faiss` in your Python code.
affects: All versions
gotchaCompatibility with NumPy 2.0 (released mid-2024) is a known issue for many C-extension libraries, including Faiss. Older `faiss-gpu` versions (like 1.7.2) are unlikely to be compatible without recompilation or patches. The `faiss-wheels` project, which typically builds these wheels, explicitly pins NumPy versions to `<2.0` in its build configurations.
fix
To avoid potential runtime errors, ensure your environment uses a NumPy version less than 2.0 (e.g., `pip install 'numpy<2.0'`).
affects: All `faiss-gpu` versions
Upgrade
Version history
1.14.3latest on PyPI · released Jun 13, 2026
Audit
Dependencies
numpyrequiredRequired for array manipulation and data handling.
Agent activity
50 hits · last 30 days
node
44
OpenAI (training)
1
Resources