voyager

library2.1.0pypypi✓ verified 85d ago

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.

vector-search ai-ml data

pip install voyager

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VOYAGER

voyager

vector-searchpythonv2.1.0

Install

4.0s avg

Import

—

Disk

106MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.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

glibc

py 3.10

✕ build_error

✓ 3.8s

py 3.11

✕ build_error

✓ 3.7s

py 3.12

✕ build_error

✓ 3.5s

py 3.13

✕ build_error

py 3.9

✕ build_error

✓ 5s

106MB installed

● package 106MB

Code

Verified usage

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

Index

✓ from voyager import Index

✗ import voyager.Index

Index is a class in the voyager module, not a submodule.

Space

✓ from voyager import Space

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]

Debug

Known issues

gotchaVoyager 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.

affects: all

deprecatedThe '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.

affects: >=2.0.0

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

fix

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

affects: all

breakingIn 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.

affects: 2.1.0 and later

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'voyager'

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

fix

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

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

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

fix

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

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

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

fix

Use 'from voyager import Index'.

Upgrade

Version history

2.1.0latest on PyPI · released Dec 13, 2024

Audit

Dependencies

numpyrequiredRequired for vector operations

Agent activity

62 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/spotify/voyager ↗

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

homepagehttps://spotify.github.io/voyager/ ↗