pynndescent

library0.6.0pypypi✓ verified 25d ago

PyNNDescent is a Python library that provides a fast and flexible implementation of Nearest Neighbor Descent for approximate nearest neighbor search and k-neighbor-graph construction. It supports a wide variety of distance metrics, sparse matrix inputs, and integrates with Scikit-learn. The current version is 0.6.0, and it maintains a regular release cadence with several minor patches and updates throughout the year.

ai-ml data vector-search

pip install pynndescent

github ↗package ↗

INSTALL

IMPORT

SIG · PYNNDESCENT

pynndescent

ai-mlpythonv0.6.0

Install

13.1s avg

Import

33484ms

Disk

477MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.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

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 13.1s · import 33.484s · 471MB

477MB installed

● package 477MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NNDescent

✓ from pynndescent import NNDescent

PyNNDescentTransformer

✓ from pynndescent import PyNNDescentTransformer

Used for scikit-learn pipeline integration.

This quickstart demonstrates how to initialize `NNDescent` with training data, prepare the index, and then query for approximate nearest neighbors. It generates random data for demonstration purposes.

import numpy as np from pynndescent import NNDescent # Generate some sample data data = np.random.rand(1000, 64).astype(np.float32) # Build the NNDescent index # n_neighbors specifies the number of neighbors to find for each point # verbose=True shows progress index = NNDescent(data, n_neighbors=15, verbose=True) # Build the index (computes the nearest neighbor graph) index.prepare() # Query the index for the 5 nearest neighbors of new data query_data = np.random.rand(10, 64).astype(np.float32) neighbors, distances = index.query(query_data, k=5) print("Shape of neighbors (query_points, k):"), print(neighbors.shape) print("Shape of distances (query_points, k):"), print(distances.shape) print("First query point's 5 nearest neighbor indices:"), print(neighbors[0]) print("First query point's 5 nearest neighbor distances:"), print(distances[0])

Debug

Known issues

deprecatedThe `n_search_trees` parameter in `NNDescent` has been deprecated. While it may still work, it's recommended to rely on the default or other parameters for controlling initialization.

fix

Remove the `n_search_trees` parameter from `NNDescent` initialization. The library will automatically choose an appropriate value.

affects: >=0.5.5

gotchaFor NumPy versions 2.0 and above, `np.infty` has been replaced with `np.inf`. PyNNDescent versions `0.5.13` and later include patches for compatibility. If using an older version of PyNNDescent with newer NumPy, this could lead to issues.

fix

Upgrade `pynndescent` to version `0.5.13` or newer, or ensure `numpy` version is compatible with your `pynndescent` installation.

affects: <0.5.13

breakingVersion `0.6.0` removed support for End-of-Life Python versions and officially added support for Python 3.12 and 3.13. If you are on an older Python version, this update may break your environment.

fix

Ensure your Python environment is running Python 3.8 or newer. Consider upgrading to Python 3.12 or 3.13 for full compatibility.

affects: 0.6.0

gotchaEarlier versions (`<0.5.9`) had bugs causing infinite recursion during random projection tree generation, especially for certain datasets or configurations. This could lead to crashes or hanging processes.

fix

Upgrade `pynndescent` to version `0.5.9` or newer, which includes fixes for these issues.

affects: <0.5.9

gotchaIn `0.5.11`, caching for functions that take distance metrics as arguments was removed. If your application relied on this caching for performance, you might observe a change in execution time after upgrading.

fix

Profile your application after upgrading to identify any performance regressions. Consider pre-calculating distances or optimizing custom distance functions if performance becomes an issue.

affects: >=0.5.11

Errors

Common errors & fixes

ImportError: cannot import name 'NNDescent' from 'pynndescent'

This error often occurs when an older version of 'umap-learn' or other libraries attempts to import 'NNDescent' directly from the top-level 'pynndescent' package, or if 'pynndescent' is not installed or is an incompatible version.

fix

Ensure 'pynndescent' is installed and updated to a compatible version, usually by running `pip install --upgrade pynndescent umap-learn`. If directly importing, the correct path is typically `from pynndescent.pynndescent_ import NNDescent` though this is usually handled internally by dependent libraries.

AttributeError: 'NNDescent' object has no attribute 'neighbor_graph'

This error indicates that the `neighbor_graph` attribute is being accessed before the approximate nearest neighbor graph has been constructed, or if a saved model from an incompatible 'pynndescent' version is being loaded.

fix

Call the `.prepare()` method on the `NNDescent` object after initialization to build the search graph. If loading a pickled object, ensure the 'pynndescent' version used for loading matches the version used for saving.

TypingError: Failed in nopython mode pipeline (step: nopython frontend)

This Numba `TypingError` typically arises from incompatibilities between the installed Numba version and the Python version, or specific features used within 'pynndescent' that conflict with the Numba runtime. It can also stem from Numba-related issues when using certain distance metrics or large datasets.

fix

Check the official 'pynndescent' documentation for compatible Numba and Python versions. Update Numba (`pip install --upgrade numba`) or downgrade to a version explicitly supported by your 'pynndescent' and Python setup.

ValueError: No hyperplanes of adequate size were found!

This error occurs during the initialization of random projection trees within 'pynndescent' (specifically in `rp_trees.py`) when the algorithm cannot construct hyperplanes with sufficient dimensions. This can happen with particular input data characteristics or when parameters related to tree construction (like `n_trees`) are unsuitable.

fix

Review your input data for uniformity or very low variance dimensions. Try adjusting the `n_trees` or `leaf_size` parameters for the `NNDescent` constructor, or in some cases, setting `tree_init=False` if random projection tree initialization is not essential for your use case.

DistributionNotFound: The 'pynndescent' distribution was not found and is required by the application.

This error means that Python's package manager cannot locate the 'pynndescent' distribution. This usually indicates an incomplete or incorrect installation of 'pynndescent', issues with the Python environment (e.g., virtual environment not activated), or a broken 'pkg_resources' mechanism.

fix

Ensure 'pynndescent' is correctly installed using `pip install pynndescent` or `conda install -c conda-forge pynndescent`. Verify that your Python virtual environment (if used) is active and that your package cache is not corrupted.

Upgrade

Version history

0.6.0latest on PyPI · released Jan 8, 2026

Audit

Dependencies

numpyrequiredCore numerical operations.

scipyrequiredScientific computing and sparse matrix support.

scikit-learnrequiredIntegration with scikit-learn pipelines, required for PyNNDescentTransformer.

numbarequiredJIT compilation for performance optimization, especially for custom distance metrics.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/lmcinnes/pynndescent ↗

packagehttps://pypi.org/project/pynndescent/ ↗