faiss-wheels 🎡

Faiss Python wheel packages.

• faiss

Overview

This repository provides CI scripts to build wheel packages for the faiss library.

• Builds wheels with cibuildwheel.
• Build backend uses scikit-build-core.
• Default BLAS backend is OpenBLAS on Linux/Windows and the Accelerate framework on macOS.
• Support various build options for customization.

Features

The PyPI distributed wheels include the following extentions.

Platform	Arch	Extensions	BLAS backend
Linux	x86_64	generic, avx2, avx512	OpenBLAS
Linux	arm64	generic, sve	OpenBLAS
macOS	x86_64	generic, avx2	Accelerate framework
macOS	arm64	generic	Accelerate framework
Windows	x86_64	generic, avx2	OpenBLAS
Windows	arm64	generic	OpenBLAS

Note GPU binary package is discontinued as of 1.7.3 release. Build a custom wheel to support GPU features.

Install

Install the CPU-only package by:

pip install faiss-cpu

Note that the package name is faiss-cpu.

Usage

Check the official documentation at the upstream for general usage.

Index portability

One caveat is that faiss indices built in a specific environment is not always compatible in the other environment. For example, indices built and saved in the x86_64 architecture is not always compatible in the arm64 environment. In addition, SIMD features can lead to incompatibility. Indices built in the AVX2 extension are not compatible in the generic extension. Faiss automatically detects the CPU instruction set and loads extensions. This tends to be an issue in the containerized environment where CPU features are not correctly detected due to driver issues.

If you encounter a segfault or weird argument errors, set the following environment variable to force or disable the specific SIMD extension:

export FAISS_OPT_LEVEL="generic"

Building customized wheels

The PyPI wheels do not support GPU by default. To support GPU methods or use faiss with a different build configuration, build a custom wheel. For building a wheel package, there are a few requirements.

• BLAS: There must be a BLAS implementation available on the Linux and Windows platforms.
• OpenMP: macOS requires libomp (available via Homebrew).
• CUDA or ROCm: A GPU development toolkit is necessary to support GPU features.

See scripts/install_* scripts for details.

Build instruction

Clone the repository with submodules.

git clone --recursive https://github.com/kyamagu/faiss-wheels.git
cd faiss-wheels

You can use a standard Python environment manager like pipx to build a wheel.

pipx run build --wheel

Any build backend supporting scikit-build-core can build wheels. For example, you can use uv to build wheels.

uv build --wheel

Build options

You can set environment variables to customize the build options. The following example builds a wheel with AVX2 and CUDA support.

export FAISS_OPT_LEVELS=avx2
export FAISS_GPU_SUPPORT=CUDA
pipx run build --wheel

Alternatively, you may directly pass CMake options via the command line. See the scikit-build-core documentation for details on how to specify CMake defines.

pipx run build --wheel \
    -Ccmake.define.FAISS_OPT_LEVELS=avx2 \
    -Ccmake.define.FAISS_GPU_SUPPORT=CUDA

The following options are available for configuration.

• FAISS_OPT_LEVELS: Optimization levels. You may set a semicolon-separated list of values from <generic|avx2|avx512|avx512_spr|sve>. For example, setting generic,avx2 will include both generic and avx2 binary extensions in the resulting wheel. This option offers more flexibility than the upstream config variable FAISS_OPT_LEVEL, which cannot specify arbitrary combinations.
• FAISS_GPU_SUPPORT: GPU support. You may set a value from <OFF|CUDA|CUVS|ROCM>. For example, setting CUDA will enable CUDA support. For CUDA, you will need the CUDA toolkit installed on the system. For ROCm, you will need the ROCm.
• FAISS_ENABLE_MKL: Intel MKL support. Default is OFF. Setting FAISS_ENABLE_MKL=ON links Intel oneAPI Math Kernel Library on Linux. You will need to install Intel oneAPI MKL before building a wheel. When OFF, the system needs a BLAS backend that CMake can find, such as OpenBLAS.
• FAISS_USE_LTO: Enable link time optimization. Default is ON. Set FAISS_USE_LTO=OFF to disable.

See also the list of supported build-time options in the upstream documentation. Do not directly set FAISS_OPT_LEVEL and FAISS_ENABLE_GPU when building a wheel via this project, as that will confuse the build process.

You might want to overwrite the default wheel package name faiss-cpu depending on the build option. Manually rewrite the name field in pyproject.toml file, or launch the following script to update the project name in pyproject.toml.

./scripts/rename_project.sh faiss-gpu

Development

This repository is intended to support PyPI distribution for the official faiss library. The repository contains the CI workflow based on cibuildwheel. Feel free to make a pull request to fix packaging problems.

Currently, GPU wheels result in a large binary size that exceeds the file size limit of PyPI.

Other relevant resources:

• Packaging projects with GPU code