{"id":14568,"library":"faiss-gpu","title":"Faiss GPU","description":"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.","status":"active","version":"1.7.2","language":"en","source_language":"en","source_url":"https://github.com/kyamagu/faiss-wheels","tags":["vector-database","similarity-search","machine-learning","gpu","cuda","embedding"],"install":[{"cmd":"pip install faiss-gpu","lang":"bash","label":"Install `faiss-gpu`"}],"dependencies":[{"reason":"Required for array manipulation and data handling.","package":"numpy","optional":false}],"imports":[{"note":"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.","wrong":"import faiss_gpu","symbol":"faiss","correct":"import faiss"}],"quickstart":{"code":"import faiss\nimport numpy as np\n\n# Check for GPU availability\nif not faiss.get_num_gpus():\n    print(\"Warning: No GPUs detected. Faiss GPU functionality will not be available.\")\n    print(\"Ensure NVIDIA drivers and CUDA toolkit are correctly installed.\")\n    # In a real application, you might exit or switch to faiss-cpu here.\n    # For this quickstart, we will proceed assuming GPU context is desired if available.\n\n# Define parameters\nd = 128      # vector dimension\nnb = 100000  # database size\nnq = 1000    # number of query vectors\nk = 4        # number of nearest neighbors to search for\n\n# Generate random data\nnp.random.seed(1234)\nxb = np.random.random((nb, d)).astype('float32')\nxb[:, 0] += np.arange(nb) / 1000.\nxq = np.random.random((nq, d)).astype('float32')\nxq[:, 0] += np.arange(nq) / 1000.\n\nprint(f\"Database vectors shape: {xb.shape}\")\nprint(f\"Query vectors shape: {xq.shape}\")\n\n# Initialize GPU resources\n# A single StandardGpuResources object handles memory management on a specific GPU.\nres = faiss.StandardGpuResources() \n\n# Create a GPU index (e.g., IndexFlatL2 for brute-force L2 distance)\n# 'res' links the index to the GPU resources, 'd' is the vector dimension.\nindex_flat = faiss.GpuIndexFlatL2(res, d)\n\n# Add vectors to the index\nprint(\"Adding vectors to GPU index...\")\nindex_flat.add(xb)\nprint(f\"Number of vectors in the index: {index_flat.ntotal}\")\n\n# Search for nearest neighbors\nprint(f\"Searching for {k} nearest neighbors for {nq} queries...\")\nD, I = index_flat.search(xq, k) # D: distances, I: indices\n\nprint(\"\\nFirst 5 query results (indices of nearest neighbors):\")\nprint(I[:5])\nprint(\"\\nFirst 5 query results (distances):\")\nprint(D[:5])","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":"1.7.2 and older on PyPI"},{"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.","message":"Using `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).","severity":"gotcha","affected_versions":"All `faiss-gpu` versions"},{"fix":"Always use `import faiss` in your Python code.","message":"While 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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"To avoid potential runtime errors, ensure your environment uses a NumPy version less than 2.0 (e.g., `pip install 'numpy<2.0'`).","message":"Compatibility 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.","severity":"gotcha","affected_versions":"All `faiss-gpu` versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[],"ecosystem":"pypi"}