Skip to main content

mlxVS

cuVS for your Mac: GPU vector search on Apple silicon.

CI License

Index a million vectors in 10 seconds, then answer 70,000 queries per second at 97.6% recall, on a MacBook Pro's GPU: twice the queries per second of HNSW on all 12 CPU cores at the same recall, from an index built 8 times faster (numbers). mlxVS brings NVIDIA cuVS's operations and parameter names to the Mac, built on MLX: exact k-NN, k-means, NN-Descent, batched all-neighbors graphs, CAGRA graph pruning and search. NumPy or MLX arrays in, any M-series Mac.

import mlxvs
graph = mlxvs.cagra_build(vectors, graph_degree=32)              # 1M x 128 in ~10 s
ids, dist = mlxvs.graph_search(vectors, graph, queries, k=10)    # ~70k queries/s at 97.6% recall
SIFT1M on a MacBook Pro M3 Pro: queries per second against recall@10. mlxVS CAGRA degree 32 (built in 10.4 s) reaches 69,500 queries/s at 0.976 recall; hnswlib on 12 CPU cores (built in 88.1 s) reaches 32,200 at 0.964. Numbers in the Benchmarks table.

Use it for approximate nearest-neighbor search, for the k-NN graph behind UMAP, t-SNE, clustering and deduplication, for exact k-NN ground truth, or as the build step of a graph index (HNSW, Vamana, CAGRA).

What's in it

Function What it does cuVS counterpart
brute_force_knn(base, queries, k) Exact k-NN: matrix multiply and a fused top-k kernel, tiled over the base brute_force::search
kmeans_fit(x, clusters), kmeans_predict(x, centroids, m) k-means++ and Lloyd; the m nearest centroids per row cluster::kmeans
nn_descent(rows, k) Approximate k-NN graph of the rows, FP16 SIMD-group joins nn_descent::build
all_neighbors(rows, k) k-NN graph built in overlapping k-means clusters, one on the GPU at a time; reads a NumPy array or memory-mapped file larger than memory where it is all_neighbors::build
cagra_build(rows, graph_degree) Search graph: k-NN graph (all_neighbors) pruned by cagra_optimize cagra::build
cagra_optimize(knn_graph, graph_degree) CAGRA's rank-based pruning (fewest two-hop detours) plus reverse edges cagra::optimize
graph_search(base, graph, queries, k) Approximate k-NN of queries by beam search of a graph, one threadgroup per query (CAGRA's single-CTA search) cagra::search
NearestNeighbors(n_neighbors).fit(X).kneighbors(Q) scikit-learn's interface over the above, NumPy in and out

Metrics: "l2" (squared), "cosine", "inner_product". Next: Vamana pruning and export to HNSW and JVector; see Roadmap.

1. Install

Needs an Apple-silicon Mac on macOS 14 or later (as MLX) and Python 3.10+.

pip install mlxvs

Wheels for Python 3.10 to 3.14 on Apple silicon, built against the mlx release they pin (MLX has no stable C++ ABI). The latest code from GitHub builds the extension against your mlx wheel; that needs the Xcode Command Line Tools (xcode-select --install) and takes about a minute:

pip install git+https://github.com/mikepapadim/mlxvs

2. Use

import numpy as np
import mlxvs

base = np.random.rand(1_000_000, 128).astype(np.float32)
queries = base[:10_000]

# exact k-NN: ids [nq, k], distances [nq, k], nearest first
ids, dist = mlxvs.brute_force_knn(base, queries, k=10, metric="l2")

# approximate k-NN graph: every row's 32 nearest other rows
graph, graph_dist = mlxvs.nn_descent(base, k=32, metric="cosine")

# the same graph in overlapping k-means clusters, as many as the GPU's memory asks for
graph, graph_dist = mlxvs.all_neighbors(base, k=32, metric="cosine")

# a search index: the k-NN graph pruned by CAGRA's rules, then queries searched over it;
# itopk_size trades speed for recall
index = mlxvs.cagra_build(base, graph_degree=32, metric="cosine")
ids, dist = mlxvs.graph_search(base, index, queries, k=10, metric="cosine", itopk_size=64)

graph = np.asarray(graph)  # results are mlx arrays; np.asarray converts without a copy
  • Inputs: MLX arrays, NumPy arrays, or anything np.asarray accepts, in any real dtype (computed in float32).
  • Outputs: int32 ids, -1 where fewer neighbors exist; float32 distances, squared for "l2", similarities (larger is closer) for "cosine" and "inner_product".
  • help(mlxvs.nn_descent) and the others document every parameter.

Data larger than memory: pass a numpy.memmap. The rows stay on disk; all_neighbors copies one cluster at a time to the GPU.

rows = np.memmap("embeddings.f32", dtype=np.float32, mode="r").reshape(-1, 1024)
graph, graph_dist = mlxvs.all_neighbors(rows, k=32, metric="cosine", verbose=True)

Coming from scikit-learn, change the import:

nn = mlxvs.NearestNeighbors(n_neighbors=10, metric="euclidean").fit(base)
distances, indices = nn.kneighbors(queries)   # NumPy arrays, scikit-learn's units
distances, indices = nn.kneighbors()          # the base rows' own neighbors

Examples: UMAP from a GPU k-NN graph and exact ground truth for an ANN benchmark (.fvecs in, .ivecs out).

C++: the same functions in include/mlxvs/mlxvs.h, taking mx::array and a trailing mx::StreamOrDevice s = {} as MLX ops do. In CMake (MLX found through CMAKE_PREFIX_PATH, e.g. Homebrew's):

add_subdirectory(mlxvs)          # or FetchContent
target_link_libraries(app PRIVATE mlxvs)

3. Run the benchmarks

curl -O ftp://ftp.irisa.fr/local/texmex/corpus/sift.tar.gz && tar xzf sift.tar.gz
pip install faiss-cpu pynndescent   # optional CPU baselines
python bench/bench_graph.py sift/sift_base.fvecs --k 32 --clusters 1,8 --baselines faiss,pynndescent

It builds the k-NN graph with each method and scores 2,000 random rows against the exact neighbors.

Search: build a graph, then recall@10 against queries per second over a sweep of itopk_size, optionally against hnswlib on the CPU.

pip install hnswlib   # optional CPU baseline
python bench/bench_search.py sift/sift_base.fvecs sift/sift_query.fvecs --degree 32 --intermediate 64 \
    --baselines hnswlib

Benchmarks

SIFT1M (985,462 x 128, L2, 10,000 queries in one batch, recall@10), MacBook Pro M3 Pro (18-core GPU, 12-core CPU), on power. mlxVS 0.1.0; hnswlib 0.8 with M=16, ef_construction=200 on all 12 cores.

Index Build Search setting Recall@10 Queries/s
mlxVS cagra_build, degree 32 (from 64) 10.4 s itopk_size 32 0.932 119,800
itopk_size 64 0.976 69,500
itopk_size 128 0.993 37,800
itopk_size 256 0.998 27,000
mlxVS cagra_build, degree 64 (from 128) 19.6 s itopk_size 32 0.977 79,500
itopk_size 64 0.994 43,600
mlxVS nn_descent k-NN graph, degree 32 (unpruned) 8.8 s itopk_size 128 0.939 42,400
hnswlib (CPU) 88.1 s ef 32 0.904 53,300
ef 64 0.964 32,200
ef 128 0.990 17,600
ef 256 0.998 10,200

Coming from cuVS

mlxvs cuVS Note
nn_descent(rows, k, ...) nn_descent::index_params::graph_degree cuVS default 64
lists of max(64, k) entries intermediate_graph_degree cuVS default 128
max_iterations = 24 max_iterations = 20 mlxvs samples 16 new neighbors per round and stops early when the lists settle
termination_threshold = 1e-4 termination_threshold = 1e-3 tuned for graph quality in JVector; pass 1e-3 for cuVS's behaviour
all_neighbors(..., n_clusters, overlap_factor) all_neighbors::index_params::{n_clusters, overlap_factor} overlap 2 as cuVS; n_clusters defaults to 0 (chosen from the GPU's memory), cuVS's to 1
algo="brute_force" / "nn_descent" all_neighbors::index_params::graph_build_params cuVS also offers IVF-PQ
"cosine" returns the cosine similarity CosineExpanded returns 1 - cosine similarities are "larger is closer"; "l2" is squared, as L2Expanded
cagra_build(rows, graph_degree=32, intermediate_graph_degree=64) cagra::index_params::{graph_degree, intermediate_graph_degree} cuVS defaults 64 and 128; NN-Descent here caps the intermediate degree at 128
cagra_optimize(knn_graph, graph_degree) cagra::optimize rank-based pruning and reverse edges, as cuVS; the reverse half fills from the lowest-rank edges
graph_search(base, graph, queries, k, ...) cagra::search takes the dataset and graph directly, no index object yet
itopk_size = 64, search_width = 1 search_params::{itopk_size, search_width} same defaults; itopk_size at most 256
max_iterations = 0 (automatic) search_params::max_iterations stops earlier once every list entry is expanded
num_random_samplings = 1 search_params::num_random_samplings random start nodes; no seed nodes yet
int32 ids int64_t ids n < 2^31 rows

Roadmap

  1. Vamana alpha pruning; export to HNSW (hnswlib) and JVector layouts (cagra::serialize_to_hnswlib).
  2. An index object holding the dataset and graph; float16 and int8 datasets for search.
  3. A C API for other languages (Java via Panama, as cuVS-java does).

How the kernels work: docs/DESIGN.md. Building, testing and code style: CONTRIBUTING.md.

License

Apache-2.0. The NN-Descent kernels are a port of JVector's jvector-gpu module (Apache-2.0, DataStax, Inc.); see NOTICE.

Metadata

Release files for mlxvs 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mlxvs 0.1.0
File Size Uploaded Provenance Actions
mlxvs-0.1.0.tar.gz 52.7 kB With provenance Details for mlxvs-0.1.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mlxvs 0.1.0
File Actions
mlxvs-0.1.0-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details for mlxvs-0.1.0-cp314-cp314-macosx_14_0_arm64.whl
mlxvs-0.1.0-cp313-cp313-macosx_14_0_arm64.whl CPython 3.13 CPython 3.13 macOS 14.0+ ARM64 Details for mlxvs-0.1.0-cp313-cp313-macosx_14_0_arm64.whl
mlxvs-0.1.0-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details for mlxvs-0.1.0-cp312-cp312-macosx_14_0_arm64.whl
mlxvs-0.1.0-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details for mlxvs-0.1.0-cp311-cp311-macosx_14_0_arm64.whl
mlxvs-0.1.0-cp310-cp310-macosx_14_0_arm64.whl CPython 3.10 CPython 3.10 macOS 14.0+ ARM64 Details for mlxvs-0.1.0-cp310-cp310-macosx_14_0_arm64.whl

Total release size: 787.8 kB

Release files / mlxvs-0.1.0.tar.gz

Download URL mlxvs-0.1.0.tar.gz
Size 52.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0628b55dd6cc77536b33214d17fe43d958b702de834316a78fbd8bd9c0499898
BLAKE2b-256 checksum
How to use checksums
5ba79a3c7e5a89c1d18579cce6ed802f02e37eb48375f917c394e534bb3f64ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mlxvs-0.1.0-cp314-cp314-macosx_14_0_arm64.whl

Download URL mlxvs-0.1.0-cp314-cp314-macosx_14_0_arm64.whl
Size 146.9 kB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
d19db003784630f8607b164408f85ea84efb8482b1a95b05f7d11e3556930ab5
BLAKE2b-256 checksum
How to use checksums
b308da35990abe891fa6a33255d632cbae6c406a730833b77c52cea987736b2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mlxvs-0.1.0-cp313-cp313-macosx_14_0_arm64.whl

Download URL mlxvs-0.1.0-cp313-cp313-macosx_14_0_arm64.whl
Size 146.9 kB
Tags CPython 3.13 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
4fcf31827de7b882cbd9be42c01f0a6313fe3de2934908c1ccf9d4287325f1cd
BLAKE2b-256 checksum
How to use checksums
30c2869184ff251bec173725b45e1937e13aae3c69399f6052ae82e3df149ce5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mlxvs-0.1.0-cp312-cp312-macosx_14_0_arm64.whl

Download URL mlxvs-0.1.0-cp312-cp312-macosx_14_0_arm64.whl
Size 146.9 kB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
0518cf0af35b6e5e0b75fa2316ea9deeccc096abd5458c2b7c7c594707c918f1
BLAKE2b-256 checksum
How to use checksums
c9b03814e9b96c79d62860dd95b00b5c42544c4733df922eb663000021981e97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mlxvs-0.1.0-cp311-cp311-macosx_14_0_arm64.whl

Download URL mlxvs-0.1.0-cp311-cp311-macosx_14_0_arm64.whl
Size 147.5 kB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
5404e0cb1751ff371e929e4c2740d5cdd0e3e4d8893476ca6f69b7798a566e53
BLAKE2b-256 checksum
How to use checksums
35506b903f40282e4134d0722906a0d1bf76161fa65d359e6d63c93f94645cfc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mlxvs-0.1.0-cp310-cp310-macosx_14_0_arm64.whl

Download URL mlxvs-0.1.0-cp310-cp310-macosx_14_0_arm64.whl
Size 146.8 kB
Tags CPython 3.10 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
17de1f265e0d4b8fe7b57bb21314c20226f0120b73c95ca13abcc4f9fcd590b9
BLAKE2b-256 checksum
How to use checksums
e450837c3b06cd16c8697404f1b0bea9ce7734faa0e7ad94ffb0a5153ff7d842
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for mlxvs 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for mlxvs-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page