{"id":6359,"library":"faiss-gpu-cu12","title":"Faiss for CUDA 12 (faiss-gpu-cu12)","description":"faiss-gpu-cu12 is a Python library for efficient similarity search and clustering of dense vectors, leveraging NVIDIA GPUs with CUDA 12. It provides pre-built wheels that dynamically link to CUDA Runtime and cuBLAS libraries available on PyPI, eliminating the need for a local CUDA installation. This particular package is an unofficial, community-maintained build, offering specialized support for CUDA 12.1 and maintaining minor version compatibility. The current version is 1.14.1.post1, with a release cadence tied to updates in the underlying Faiss library and CUDA versions.","status":"active","version":"1.14.1.post1","language":"en","source_language":"en","source_url":"https://github.com/Di-Is/faiss-gpu-wheels","tags":["vector search","GPU","CUDA","similarity search","AI","machine learning","embeddings"],"install":[{"cmd":"pip install faiss-gpu-cu12","lang":"bash","label":"Standard installation (allows CUDA 12.x, x>=1)"},{"cmd":"pip install 'faiss-gpu-cu12[fix-cuda]'","lang":"bash","label":"Installation with fixed CUDA 12.1 (requires NVIDIA Driver ≥R530)"}],"dependencies":[{"reason":"Required for array manipulation with Faiss.","package":"numpy","optional":false},{"reason":"Dynamically linked dependency for CUDA 12 runtime, installed automatically by pip.","package":"nvidia-cuda-runtime-cu12","optional":false},{"reason":"Dynamically linked dependency for cuBLAS, installed automatically by pip.","package":"nvidia-cublas-cu12","optional":false}],"imports":[{"symbol":"faiss","correct":"import faiss"}],"quickstart":{"code":"import faiss\nimport numpy as np\n\n# 1. Define dataset parameters\nd = 128      # dimension\nnb = 100000  # database size\nnq = 10      # number of queries\n\n# 2. Generate random data\nnp.random.seed(1234)\nxb = np.random.random((nb, d)).astype('float32')\nxq = np.random.random((nq, d)).astype('float32')\n\n# Ensure the data is C-contiguous as Faiss often expects it\nxb = np.ascontiguousarray(xb)\nxq = np.ascontiguousarray(xq)\n\n# 3. Build a CPU index (e.g., L2 distance)\nindex_cpu = faiss.IndexFlatL2(d)\nprint(f\"Is CPU index trained? {index_cpu.is_trained}\")\n\n# 4. Add vectors to the CPU index\nindex_cpu.add(xb)\nprint(f\"Number of vectors in CPU index: {index_cpu.ntotal}\")\n\n# 5. Attempt to move the index to GPU\ntry:\n    # Faiss GPU indices require StandardGpuResources\n    res = faiss.StandardGpuResources()\n    # 0 for the first GPU; change if you have multiple and want a different one\n    index_gpu = faiss.index_cpu_to_gpu(res, 0, index_cpu)\n    print(f\"\\nIndex successfully moved to GPU. Number of vectors: {index_gpu.ntotal}\")\n\n    # 6. Perform search on GPU\n    k = 4 # We want to find 4 nearest neighbors\n    D, I = index_gpu.search(xq, k) # D for distances, I for indices\n\n    print(\"\\nGPU Search - Distances (D):\")\n    print(D)\n    print(\"\\nGPU Search - Indices (I):\")\n    print(I)\n\nexcept Exception as e:\n    print(f\"\\nCould not run GPU operations. This might happen if no compatible GPU or drivers are found, or if it's a CPU-only environment. Error: {e}\")\n    print(\"Falling back to CPU search for demonstration:\")\n    k = 4\n    D_cpu, I_cpu = index_cpu.search(xq, k)\n    print(\"\\nCPU Search - Distances (D):\")\n    print(D_cpu)\n    print(\n\"\\nCPU Search - Indices (I):\")\n    print(I_cpu)","lang":"python","description":"This quickstart demonstrates how to create a simple Faiss index on the CPU, populate it with random data, then move it to an available GPU for accelerated similarity search. It includes a fallback to CPU search in case of GPU environment issues."},"warnings":[{"fix":"Ensure your system has an up-to-date NVIDIA driver (R530+ for CUDA 12.1, R550+ for CUDA 12.4) and a supported GPU. Refer to NVIDIA's CUDA compatibility documentation for details.","message":"NVIDIA Driver and GPU Architecture Compatibility: This package requires a CUDA-compatible NVIDIA driver and a GPU with Compute Capability 7.0–8.9 (Volta to Ada Lovelace). Older GPUs or incompatible drivers will prevent Faiss from leveraging GPU acceleration.","severity":"breaking","affected_versions":"All versions"},{"fix":"Use `pip install 'faiss-gpu-cu12[fix-cuda]'` to enforce CUDA 12.1 explicitly. Carefully manage your environment dependencies or use isolated environments (e.g., conda, virtualenv) for different CUDA-dependent projects.","message":"CUDA Version Conflicts with Other Libraries: When integrating `faiss-gpu-cu12` with other CUDA-dependent libraries like PyTorch or TensorFlow in the same environment, ensure they are all linked to the same CUDA 12.x version to avoid runtime conflicts and errors. Different CUDA minor versions may introduce incompatibilities.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential edge cases or lack of support for very new or niche hardware. For critical enterprise applications, consider contributing to the project, building Faiss from source with official instructions, or using official distributions if available.","message":"Unofficial Project Status: The `faiss-gpu-cu12` package is an unofficial, community-maintained project, not directly from Facebook AI Research. This implies potential limitations in comprehensive testing across all NVIDIA GPU architectures and varying levels of support compared to the official Faiss repository.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using H100/Hopper GPUs, avoid `faiss-gpu-cu12==1.13.2`. Check the project's GitHub releases or issues for newer versions that explicitly include `sm_90` kernels, or consider building Faiss from source with `sm_90` support enabled.","message":"Missing sm_90 (Hopper/H100) Kernels for Version 1.13.2: Specifically, `faiss-gpu-cu12==1.13.2` is known to be missing `sm_90` CUDA kernels, causing runtime failures on NVIDIA H100/Hopper GPUs, despite its PyPI description claiming support for compute capability up to 9.0. It only contains `sm_70` and `sm_80` kernels.","severity":"breaking","affected_versions":"1.13.2"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}