Metadata-Version: 2.2
Name: faiss-gpu-cu11
Version: 1.14.0
Summary: A library for efficient similarity search and clustering of dense vectors.
Keywords: search nearest neighbors
Author-Email: Di-Is <rhoxbox@gmail.com>
License: MIT License
         
         Copyright (c) 2024 Di-Is
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
         The major design pattern of this repository was based in Kota Yamaguchi's faiss-wheels, which is subject to the same license.
         Here is the original copyright notice for faiss-wheels:
         
         MIT License
         
         Copyright (c) 2019 Kota Yamaguchi
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
         This repository uses meta's faiss and is subject to the same license.
         Here is the original copyright notice for faiss:
         
         MIT License
         
         Copyright (c) Facebook, Inc. and its affiliates.
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: GPU :: NVIDIA CUDA :: 11
Project-URL: faiss-gpu-wheels, https://github.com/Di-Is/faiss-gpu-wheels
Requires-Python: <3.14,>=3.10
Requires-Dist: numpy<3,>=2
Requires-Dist: packaging
Requires-Dist: nvidia-cuda-runtime-cu11>=11.8.89
Requires-Dist: nvidia-cublas-cu11>=11.11.3.6
Provides-Extra: fix-cuda
Requires-Dist: nvidia-cuda-runtime-cu11==11.8.89; extra == "fix-cuda"
Requires-Dist: nvidia-cublas-cu11==11.11.3.6; extra == "fix-cuda"
Description-Content-Type: text/markdown

# faiss-wheels

This repository is based on [kyamagu/faiss-wheels](https://github.com/kyamagu/faiss-wheels).

[![PyPI](https://img.shields.io/pypi/v/faiss-gpu-cu11?label=faiss-gpu-cu11)](https://pypi.org/project/faiss-gpu-cu11/)
[![PyPI](https://img.shields.io/pypi/v/faiss-gpu-cu12?label=faiss-gpu-cu12)](https://pypi.org/project/faiss-gpu-cu12/)

## Overview

This repository provides scripts to build GPU-enabled wheels for the [faiss](https://github.com/facebookresearch/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](https://docs.nvidia.com/deploy/cuda-compatibility/))

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](https://github.com/sponsors/Di-Is) to help cover the hardware and infrastructure costs. For ongoing discussion and status updates, see [Support for New GPU Architectures](https://github.com/Di-Is/faiss-gpu-wheels/discussions/120).

### 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](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md)
2. **Build from Source**: Use this repository's code to build wheels for your specific architecture (see [Building from Source](#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

```bash
# 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

```bash
# 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

| CUDA Version | Minimum Driver Version |
|--------------|------------------------|
| CUDA 11.8    | ≥R520 (520.61.05)      |
| CUDA 12.1    | ≥R530 (530.30.02)      |
| CUDA 12.2+   | Check [NVIDIA Documentation](https://docs.nvidia.com/deploy/cuda-compatibility/) |

**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](https://github.com/astral-sh/uv/issues/7214), [pdm](https://pdm-project.org/en/latest/usage/config/#exclude-specific-packages-and-their-dependencies-from-the-lock-file))
2. **Set environment variable**: `_FAISS_WHEEL_DISABLE_CUDA_PRELOAD=1`
3. **Ensure CUDA libraries are accessible** via `LD_LIBRARY_PATH`

Example with uv (workaround):

```toml
# 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](https://github.com/pypa/cibuildwheel).

### Build Configuration

```bash
# 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

```bash
# 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)
