Install & Compatibility
Where this runs
tested against v1.4.2 · 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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 19.4s · import 5.547s · 2252.8MB
2253MB installed
● package 2253MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
scann
✓ import scann
Main module for ScaNN's Python API.
scann_ops_pybind
✓ import scann
searcher = scann.scann_ops_pybind.builder(...).build()
Accesses the native Python bindings for ScaNN, used for building searchers without TensorFlow dependencies.
scann_ops
✓ import scann
searcher = scann.scann_ops.builder(...).build()
✗ from scann import ScannBuilder
Accesses the TensorFlow op bindings for ScaNN. Requires `scann[tf]` to be installed. The `ScannBuilder` class is typically accessed via `scann.scann_ops.builder()` or `scann.scann_ops_pybind.builder()`.
This quickstart demonstrates how to create a ScaNN searcher with a sample dataset, configure it for Maximum Inner Product Search (MIPS) using tree partitioning and anisotropic quantization, and then perform a similarity search. It uses the native Python API (`scann.scann_ops_pybind`) which does not require TensorFlow. The example generates random data for simplicity, but in a real application, `dataset` would be your actual high-dimensional vectors (e.g., embeddings).
import numpy as np
import scann
# 1. Prepare your dataset (e.g., embeddings)
# For demonstration, creating a random dataset of 1000 vectors, 128 dimensions each.
dataset = np.random.rand(1000, 128).astype(np.float32)
# 2. Build the ScaNN searcher
# This example uses dot product distance for Maximum Inner Product Search (MIPS).
# num_leaves: Number of leaves in the tree for partitioning.
# num_leaves_to_search: Number of leaves to search at query time.
# anisotropic_quantization_threshold: Parameter for Anisotropic Vector Quantization.
searcher = scann.scann_ops_pybind.builder(
dataset,
num_neighbors=10, # Number of nearest neighbors to retrieve
distance_measure="dot_product"
).tree(
num_leaves=100,
num_leaves_to_search=10
).score_ah(
dimensions_per_block=2, # Recommended for MIPS
anisotropic_quantization_threshold=0.2
).reorder(
100 # Rescore top 100 candidates to improve accuracy
).build()
# 3. Define a query vector
query = np.random.rand(128).astype(np.float32)
# 4. Perform a search
neighbors, distances = searcher.search(query)
print(f"Query vector shape: {query.shape}")
print(f"Dataset shape: {dataset.shape}")
print(f"Found {len(neighbors)} neighbors: {neighbors}")
print(f"Corresponding distances: {distances}")
Errors
Common errors & fixes
ERROR: Could not find a version that satisfies the requirement scann (from versions: none)
ERROR: No matching distribution found for scann
This error typically occurs if your Python version is not within the supported range (e.g., <3.9 or >=3.14 for current versions), if your operating system architecture is not supported by available wheels (e.g., macOS or Windows without WSL), or if pip is outdated.
fixCheck your Python version (`python --version`) and ensure it's compatible. Upgrade pip (`pip install --upgrade pip`). If on macOS/Windows, consider using a Linux environment (e.g., Docker, WSL) or building from source.
TypeError: builder() missing 3 required positional arguments: 'db', 'num_neighbors', and 'distance_measure'
This indicates an incorrect call to the `builder()` method, usually from `scann.scann_ops_pybind` or `scann.scann_ops`. The `builder()` method requires the dataset, number of neighbors to retrieve, and the distance measure (e.g., 'dot_product', 'squared_l2') as its initial arguments.
fixEnsure you are passing the `dataset` (a numpy array), `num_neighbors` (an integer), and `distance_measure` (a string) to `builder()`: `scann.scann_ops_pybind.builder(dataset, num_neighbors=10, distance_measure="dot_product")`.
ERROR: Cannot create ScaNN index with empty table.
The ScaNN builder (or related indexing functions) was provided with an empty dataset or a dataset that became empty after filtering. ScaNN requires data to build its index.
fixEnsure that the `dataset` array passed to the ScaNN builder is not empty and contains valid embedding vectors before attempting to build the searcher.
Upgrade
Version history
1.4.2latest on PyPI · released Aug 29, 2025
Audit
Dependencies
PythonrequiredRequires Python >=3.9, <3.14.
libstdc++requiredRequires libstdc++ version 3.4.23 or above from the operating system for manylinux_2_27 wheels.
tensorflowoptionalOptional for TensorFlow op bindings, installed via `scann[tf]`.