Voyager

2.1.1 verified Mon Apr 27 auth: no python

Voyager is an approximate nearest neighbor search library optimized for speed and memory, supporting both L2 and cosine distance. It provides Python, Java, and C++ bindings. Current version: 2.1.1, released 2025-01-13. Release cadence: irregular, with multiple minor/patch releases per year.

pip install voyager

Common errors

error ModuleNotFoundError: No module named 'voyager' ↓

cause Voyager is not installed or the wrong package name is used.

fix

Run 'pip install voyager' (not 'voyager-search' or 'voyager-ann').

error TypeError: __init__() got an unexpected keyword argument 'num_dimensions' ↓

cause Incorrect argument name; constructor expects 'num_dimensions' (old versions used 'd' or 'dimension').

fix

Use Index(Space.L2, num_dimensions=3).

error AttributeError: module 'voyager' has no attribute 'Index' ↓

cause Importing from a submodule instead of the top-level package.

fix

Use 'from voyager import Index'.

Warnings

gotcha Voyager uses float32 internally; passing float64 vectors will cause silent conversion and may affect performance. ↓

fix Ensure input vectors are np.float32 to avoid conversion overhead.

deprecated The 'Space' enumeration values (e.g., Space.L2, Space.Cosine) are preferred over the older string-based distance specification. ↓

fix Use Space.L2 instead of 'l2' or 0.

gotcha Index.query returns (distances, ids) tuples; it is easy to forget the order and assume (ids, distances). ↓

fix Always unpack as distances, ids = index.query(...).

breaking In v2.1.0, the Python bindings were migrated to Nanobind; this may affect how custom data types or callbacks are passed. ↓

fix If you use custom Python objects for IDs, ensure they are convertible to int64. Review migration notes.

Imports

Index
wrong
```
import voyager.Index
```
correct
```
from voyager import Index
```
Index is a class in the voyager module, not a submodule.
Space
```
from voyager import Space
```

Quickstart

Basic example: create index, add vectors, query nearest neighbors.

import numpy as np
from voyager import Index, Space

# Create an index with L2 distance
index = Index(Space.L2, num_dimensions=3)
# Add items (vectors and optional IDs)
vectors = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], dtype=np.float32)
index.add_items(vectors, ids=[0, 1])
# Query
query = np.array([1.5, 2.5, 3.5], dtype=np.float32)
distances, ids = index.query(query, k=2)
print(ids)  # [0, 1]