Install & Compatibility
Where this runs
tested against v2.18.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 12.95s
412MB installed
● package 412MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
build_index
✓ from autofaiss import build_index
This is the primary function for automatically selecting and building a Faiss index.
This quickstart demonstrates how to build a Faiss index using `autofaiss.build_index` from a NumPy array. It highlights essential parameters like `index_path`, `max_ram_usage`, and `metric_type`. The `max_ram_usage` parameter is critical for preventing out-of-memory errors on large datasets.
import numpy as np
from autofaiss import build_index
# Create dummy data: 1000 vectors of 128 dimensions, float32 is recommended
data = np.float32(np.random.rand(1000, 128))
# Build the index. Specify max_ram_usage relevant to your system.
# For production, consider 'metric_type="ip"' for inner product or 'l2' for L2 distance.
index, index_infos = build_index(
data,
index_path="my_autofaiss_index.bin",
index_infos_path="my_autofaiss_index_infos.json",
max_ram_usage="4GB", # IMPORTANT: Adjust based on available RAM
metric_type="ip"
)
print(f"Index built and saved to my_autofaiss_index.bin with info in my_autofaiss_index_infos.json")
autofaiss --version
Debug
Known issues
gotchaBuilding large Faiss indices, especially with `autofaiss`, can be very memory-intensive. Users frequently encounter Out-of-Memory (OOM) errors if the `max_ram_usage` parameter is not set appropriately for their system's available RAM or if it's omitted.fixAlways explicitly set `max_ram_usage` in `build_index` to a value comfortably below your system's physical RAM (e.g., '4GB', '16GB', etc.). Monitor memory usage during index building.
affects: All versions
gotchaFor GPU acceleration, `autofaiss` requires the `faiss-gpu` dependency. Simply installing `autofaiss` (which pulls `faiss-cpu`) will not enable GPU support. Attempting to use GPU features without `faiss-gpu` installed will result in runtime errors or fall back to CPU.fixInstall with `pip install autofaiss[gpu]`. Ensure you have a compatible NVIDIA CUDA toolkit and drivers installed on your system. Do not install `faiss-cpu` and `faiss-gpu` simultaneously.
affects: All versions
gotchaFaiss, and by extension AutoFaiss, is optimized for and often expects input vectors to be of `np.float32` data type. Passing `np.float64` (the default for many NumPy operations) can significantly increase memory consumption, reduce performance, and potentially lead to Out-of-Memory errors for large datasets.fixEnsure your input data is explicitly cast to `np.float32` before passing it to `build_index`. Example: `data = np.float32(your_raw_data)`.
affects: All versions
breakingAutoFaiss requires Python >= 3.10. Attempting to install or run AutoFaiss on older Python versions will lead to dependency resolution errors, installation failures, or `SyntaxError` on import.fixUpgrade your Python environment to Python 3.10 or newer. Use virtual environments to manage different Python versions if needed.
affects: < 2.0 (for Python < 3.8); >= 2.0 (for Python < 3.10)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'faiss_gpu'
Attempting to use GPU features (e.g., setting `use_gpu=True` implicitly or explicitly) when only `faiss-cpu` is installed, or when `autofaiss[gpu]` was not used for installation.
fixTo enable GPU support, install AutoFaiss with the `[gpu]` extra: `pip install autofaiss[gpu]`. Ensure your system has a compatible NVIDIA CUDA setup. If you don't intend to use GPU, remove any GPU-related configurations.
TypeError: Expected np.float32 for input vectors, got np.float64.
The input data (embeddings) provided to `build_index` is in `np.float64` format, while Faiss prefers and is optimized for `np.float32`.
fixConvert your input NumPy array to `np.float32` before passing it to `build_index`. For example: `data = np.float32(your_data)`.
ValueError: max_ram_usage is too low to build an index for the given data. Required RAM: X.XGB, Available RAM: Y.YGB.
AutoFaiss's internal logic determined that the `max_ram_usage` specified (or default) is insufficient for the size and dimensionality of your input data.
fixIncrease the `max_ram_usage` parameter in your `build_index` call to a higher value, ensuring it doesn't exceed your system's physical RAM. Example: `max_ram_usage='16GB'`.
Upgrade
Version history
2.18.0latest on PyPI · released Nov 20, 2025
Audit
Dependencies
faiss-cpurequiredCore Faiss library for CPU-based indexing. Automatically installed with `pip install autofaiss`.
faiss-gpuoptionalEnables GPU acceleration for index building and searching. Requires `pip install autofaiss[gpu]` and a compatible NVIDIA CUDA setup.
numpyrequiredFundamental package for numerical operations and array handling.
pandasrequiredUsed for data manipulation, particularly for input data handling and metadata.
scikit-learnrequiredProvides various machine learning utilities, often used for data preprocessing.