Registry / ai-ml / scann
library1.4.2pypypi✓ verified 85d ago

ScaNN (Scalable Nearest Neighbors) is a library by Google Research for efficient vector similarity search at scale, implementing techniques like search space pruning and quantization. It offers both Python and TensorFlow APIs and is known for its speed and scalability with large datasets. The current version is 1.4.2, actively maintained, and released through PyPI.

pip install scann
INSTALL
IMPORT
SIG · SCANN
S
scann
ai-mlpythonv1.4.2
Install
19.4s avg
Import
5547ms
Disk
2253MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
build_error
glibc
py 3.103.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}")
Debug
Known issues
breakingScaNN has strict Python version requirements and specific TensorFlow version compatibility. For example, ScaNN 1.2.0 dropped Python 3.5 support and was built against TensorFlow 2.4.0, making it incompatible with TensorFlow 2.3.x. More recent versions (e.g., 1.4.x) support Python 3.9-3.13.
fix
Always check `requires_python` on PyPI and consult `docs/releases.md` on GitHub for specific version compatibility with Python and TensorFlow. Upgrade or downgrade your Python/TensorFlow environment as needed.
affects: <1.4.x
breakingAs of ScaNN 1.4.0, TensorFlow op bindings are no longer enabled by default. `pip install scann` will *not* include TensorFlow integration.
fix
If you intend to use ScaNN's TensorFlow ops (e.g., for SavedModels), install with `pip install scann[tf]`.
affects: >=1.4.0
gotchaScaNN wheels have system-level dependencies. x86 wheels require AVX and FMA instruction set support, while ARM wheels require NEON. Additionally, `manylinux_2_27` compatible wheels require `libstdc++` version 3.4.23 or above.
fix
Ensure your system's CPU supports the required instruction sets and `libstdc++` meets the version requirement. If not, consider building from source or using a compatible environment (e.g., Docker for Linux environments on incompatible systems).
affects: All
deprecatedThe `ScannBuilder` API underwent changes in version 1.1.0. Rather than calling `create_tf` or `create_pybind` directly on a `ScannBuilder` object, you now use the `builder()` method from `scann_ops` or `scann_ops_pybind` to get a `ScannBuilder` object, and then call `build()` on it.
fix
Update your code to use the modern builder pattern: `scann.scann_ops_pybind.builder(...).build()`.
affects: <1.1.0
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.
fix
Check 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.
fix
Ensure 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.
fix
Ensure 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]`.
Agent activity
55 hits · last 30 days
node
46
OpenAI (training)
1
Resources