faiss-wheels

This repository is based on kyamagu/faiss-wheels.

Overview

This repository provides scripts to build GPU-enabled wheels for the faiss library. Distributes faiss-gpu-cuXX packages to PyPI using the contents of this repository.

Key Features

• No local CUDA installation required - Dynamically links to CUDA Runtime and cuBLAS libraries from PyPI
• Builds CUDA 11.8+ and CUDA 12.1+ compatible wheels
• Supports Volta to Ada Lovelace architecture GPUs (Compute Capability 7.0–8.9)
• Bundles OpenBLAS in Linux
• Reduces wheel file size through dynamic linking instead of static compilation

Important Requirements

The published faiss-gpu-cuXX packages require proper system setup that cannot be managed by pip. It is your responsibility to prepare a suitable environment:

1. NVIDIA Driver: Your host must have a CUDA-compatible NVIDIA driver installed

   • The minimum driver version depends on the CUDA version that gets installed
   • NVIDIA drivers are backward compatible with older CUDA versions (See CUDA Compatibility Documentation)

2. GPU Architecture: Your GPU must be compatible (Compute Capability 7.0–8.9)

   • Supported: Volta, Turing, Ampere, Ada Lovelace

3. Library Compatibility: If you install multiple CUDA-dependent libraries (e.g., PyTorch) in the same environment, they must link to the same CUDA version

GPU Architecture Support for PyPI Packages

Support Policy for faiss-gpu-cu11 and faiss-gpu-cu12

Note: This is an unofficial, personal development project with limited computational resources. Due to these constraints, comprehensive testing across all NVIDIA GPU architectures is not feasible. The pre-built faiss-gpu-cu11 and faiss-gpu-cu12 packages on PyPI aim to support the same GPU architecture range (Compute Capability 7.0–8.9) as the official Faiss repository.

Sponsoring New GPU Architecture Support

Adding support for a new GPU architecture (e.g., Hopper, Blackwell) requires dedicated hardware for building and testing. NVIDIA GPUs have limited compatibility across compute capabilities — binaries built for one architecture do not necessarily work correctly on another. Distributing untested wheels is not an option.

This is an unfunded personal project. If you or your organization need support for an architecture outside the current range, please consider sponsoring this project to help cover the hardware and infrastructure costs. For ongoing discussion and status updates, see Support for New GPU Architectures.

For Unsupported GPU Architectures

If you have a GPU architecture that is not supported by these pre-built wheels:

1. Official Faiss: Follow the official Faiss repository build instructions
2. Build from Source: Use this repository's code to build wheels for your specific architecture (see Building from Source section)

Installation

The faiss-gpu-cu11 and faiss-gpu-cu12 wheels are available on PyPI. Choose the appropriate version for your CUDA environment.

For CUDA 12

# Install with fixed CUDA 12.1 (requires NVIDIA Driver ≥R530)
pip install 'faiss-gpu-cu12[fix-cuda]'

# Install with CUDA 12.X (X≥1) - allows flexibility but driver requirement varies
pip install faiss-gpu-cu12

Details:

• faiss-gpu-cu12 is built with CUDA Toolkit 12.1 and maintains minor version compatibility
• With [fix-cuda]: Installs exactly CUDA 12.1, requiring NVIDIA Driver ≥R530
• Without [fix-cuda]: Allows any CUDA 12.X (X≥1), driver requirement depends on the actual CUDA version installed
  • For example: CUDA 12.4 requires Driver ≥R550
• Use without [fix-cuda] when integrating with other CUDA-dependent packages (e.g., PyTorch with CUDA 12.4)

System Requirements:

• OS: Linux x86_64 (glibc ≥2.17)
• GPU: Compute Capability 7.0–8.9

For CUDA 11

# Install with CUDA 11.8 (requires NVIDIA Driver ≥R520)
pip install faiss-gpu-cu11[fix-cuda]

# Same as above (CUDA 11.8 is the final version)
pip install faiss-gpu-cu11

Details:

• faiss-gpu-cu11 is built with CUDA Toolkit 11.8
• Both commands install CUDA 11.8 since no newer CUDA 11.X versions exist
• Requires NVIDIA Driver ≥R520

System Requirements:

• OS: Linux x86_64 (glibc ≥2.17)
• GPU: Compute Capability 7.0–8.9

Driver Compatibility Reference

Warning: When installing without [fix-cuda], pip may resolve to a newer CUDA version that requires a newer driver than you have installed. Always verify driver compatibility before installation.

Advanced: Using System CUDA Libraries

If you need to use system-installed CUDA instead of PyPI CUDA packages, you can bypass the automatic CUDA loading:

1. Exclude PyPI CUDA dependencies using your package manager (e.g., uv, pdm)
2. Set environment variable: _FAISS_WHEEL_DISABLE_CUDA_PRELOAD=1
3. Ensure CUDA libraries are accessible via LD_LIBRARY_PATH

Example with uv (workaround):

# In pyproject.toml
[tool.uv]
override-dependencies = [
    "nvidia-cuda-runtime-cu11==0.0.0; sys_platform == 'never'",
    "nvidia-cublas-cu11==0.0.0; sys_platform == 'never'",
]

Versioning

• Follows the original faiss repository versioning (e.g., 1.11.0)
• Patches specific to this repository use postN suffix (e.g., 1.11.0.post1)

Building from Source

Build faiss-gpu-cu11 and faiss-gpu-cu12 wheels using cibuildwheel.

Build Configuration

# Configure build parameters
export NJOB="32"                          # Number of parallel build jobs
export FAISS_OPT_LEVEL="generic"          # Options: generic, avx2, avx512
export CUDA_ARCHITECTURES="70-real;80-real"  # Target GPU architectures

# For builds without GPU testing
export CIBW_TEST_COMMAND_LINUX=""

# For builds with GPU testing (requires NVIDIA Docker)
export CIBW_CONTAINER_ENGINE='docker; create_args: --gpus all'
# Note: GPU testing requires Docker with NVIDIA Container Toolkit configured

Build Commands

# Build faiss-gpu-cu11 wheels
uvx cibuildwheel@2.23.2 variant/gpu-cu11 --output-dir wheelhouse/gpu-cu11

# Build faiss-gpu-cu12 wheels
uvx cibuildwheel@2.23.2 variant/gpu-cu12 --output-dir wheelhouse/gpu-cu12

Wheels will be created in {repository_root}/wheelhouse/gpu-cuXX/.

Build Requirements

• OS: Linux x86_64
• NVIDIA Container Toolkit (if running tests)
• NVIDIA Driver: ≥R530 (if running tests with CUDA 12)