snapvec
Fast compressed approximate nearest-neighbor search. NumPy + Cython compiled kernels.
Four index types for embedding vector search, each targeting a different point on the accuracy / storage / latency frontier:
| Index | Training | Compression | Recall | Use when |
|---|---|---|---|---|
SnapIndex |
none | 6-12x | 0.92+ | Any distribution, no corpus sample |
ResidualSnapIndex |
none | 4-8x | 0.96 | Higher recall, still training-free |
PQSnapIndex |
one-off fit |
24-96x | 0.95 | Modern LLM embeddings, aggressive compression |
IVFPQSnapIndex |
one-off fit |
24-96x | 0.98 | Sub-linear search at scale (N > 100k) |
Three numbers from v0.11.0 on BEIR FIQA (N = 57,638, dim = 384 BGE-small, Apple M4 Pro, single-thread, 200 queries, point area proportional to on-disk footprint):
- 0.945 recall @ 345 us: IVFPQ + fp16 rerank. Pareto-dominant under 500 us on this corpus.
- 0.895 recall @ 319 us: IVFPQ at matched FAISS M=192 budget (12.6 MB). 1.4x faster than FAISS at essentially the same recall.
- 0.649 recall @ 263 us at 4.9 MB: IVFPQ + OPQ at the aggressive M=48 corner. Beats FAISS IVFPQ M=48 on recall (+4.6 pp) at comparable disk; FAISS wins the same corner on latency (144 us).
Scope: one dataset, one hardware class. Run
python experiments/bench_competitive.py on your own corpus before
citing these as general claims. See
benchmarks for the
full matched-budget table, OPQ recall-vs-M sweep, threading curve,
and N-scaling comparison vs sqlite-vec.
Install
pip install snapvec
On macOS you also need brew install libomp to build from source; the
wheels on PyPI bundle it.
Quickstart
import numpy as np
from snapvec import SnapIndex
rng = np.random.default_rng(0)
corpus = rng.standard_normal((10_000, 384)).astype(np.float32)
idx = SnapIndex(dim=384, bits=4, seed=0)
idx.add_batch(list(range(10_000)), corpus)
query = rng.standard_normal(384).astype(np.float32)
for doc_id, score in idx.search(query, k=10):
print(doc_id, score)
idx.save("my.snpv")
Runnable end-to-end scripts for every index live in
examples/.
Documentation
Full docs: https://stffns.github.io/snapvec/
- Installation
- Choosing an index
- Architecture (RHT, Lloyd-Max, PQ, IVF)
- Benchmarks
- API reference
Context
snapvec was developed as the quantization layer for
vstash, a local-first hybrid retrieval
system, to extend it to corpora beyond the float32 memory budget while
preserving its dependency-minimal design. It stands alone as a
quantization library, but the design constraints (NumPy-only base
install, predictable latency, reproducible index files) come from
vstash's local-first requirements.
Roadmap
See ROADMAP.md for planned work and explicit non-goals.
Contributing
See CONTRIBUTING.md for dev setup, the test matrix, and the release process. Bugs and feature requests go to issues; questions and usage help to discussions.
License
MIT (c) 2025 Jayson Steffens.
The TurboQuant algorithm is described in arXiv:2504.19874 by Zandieh et al. (Google Research / ICLR 2026). This package is an independent implementation.
1 maintainer
Metadata
1 maintainer
Release files for snapvec 0.11.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| snapvec-0.11.1.tar.gz | 255.0 kB | Details |
Built distributions (wheels)
Total release size: 9.9 MB
Release files / snapvec-0.11.1.tar.gz
| Download URL | snapvec-0.11.1.tar.gz |
|---|---|
| Size | 255.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
51e05a318ceb9bae8fd9dae10d1cfe056c012befd05314a2d071ef92c5f23775
|
|
BLAKE2b-256 checksum How to use checksums |
02dc4d1c260c778635e3254864d3d59f80fd77ba4705806494d4d978a727599a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp313-cp313-win_amd64.whl
| Download URL | snapvec-0.11.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 283.7 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7b8894fe1c1c10a941179ea629c13dc23fc7ee6249cf04a823df50b45dafb3c4
|
|
BLAKE2b-256 checksum How to use checksums |
02b6478e62e423eb135d03a90cc01bc2d7bb182760ea20846ecd1b0bea63321b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | snapvec-0.11.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 807.7 kB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
68132065e8530b54b0634d3729bde7bc4f01090b2052490554db5f47785bce6b
|
|
BLAKE2b-256 checksum How to use checksums |
a4703ea8cb79848abb76f3d8c43b089b59dc0852bf0d48260e92fb5c5a7873ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | snapvec-0.11.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 791.8 kB |
| Tags | CPython 3.13 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
56f5e3186e7ea31b5a78e31e231355e2ade0681e50b1ff7b878c99e722b8edff
|
|
BLAKE2b-256 checksum How to use checksums |
27859fb74ac366844fe2e8617ced7e765ff947a72a31e834b5c0bd81ebc9855b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp313-cp313-macosx_14_0_arm64.whl
| Download URL | snapvec-0.11.1-cp313-cp313-macosx_14_0_arm64.whl |
|---|---|
| Size | 529.1 kB |
| Tags | CPython 3.13 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ff8b8c7d6cf40782df8507833c786f3831062a66e141e6ecb6858885d69a1f84
|
|
BLAKE2b-256 checksum How to use checksums |
bc514c0e7e262a407a0d0d9bb5873cd054e9398b22bc630bbd5c7519f5f39029
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp312-cp312-win_amd64.whl
| Download URL | snapvec-0.11.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 284.0 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
eb378d6358865d2dc44d7edcd66d39bf1b767225972598996da61f85e6c5efc3
|
|
BLAKE2b-256 checksum How to use checksums |
bd6e1bed9f5fe8cc45952090236463efa796a771984b17715e2205453157204d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | snapvec-0.11.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 812.4 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
e900cb915c5aa965c5d4241861b89010a271f132bd47a7b018f6d4793da6063e
|
|
BLAKE2b-256 checksum How to use checksums |
25fe257cb63118ac9cffcfbe848b7a1b23af68abcf99c78c467ebd591ee0da08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | snapvec-0.11.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 796.4 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
8f6f9d380783c8fdca6c61685227aadb66a3998366ffec38317f56e1a5f422d0
|
|
BLAKE2b-256 checksum How to use checksums |
6418c2d02249365e801059086570c920c7674d416068dacb1e46ba7d95c773ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | snapvec-0.11.1-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 529.8 kB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
275c3b62241c4bd7d51dfbb7ffd47a4a7681caed20c63fe782eb0e6e06414be3
|
|
BLAKE2b-256 checksum How to use checksums |
140a1c1ca7859fe1dfb619880c185b5a4e15fc981a44af9acdc7699c466508cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp311-cp311-win_amd64.whl
| Download URL | snapvec-0.11.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 282.7 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
cc1b23792e32a7c688d3feb0e4090137887db7a5e8981a9b9e352865a2399cea
|
|
BLAKE2b-256 checksum How to use checksums |
a9ec9a0999922bb8e10074ee65d9b4a9cf63a8c60544aa0c9d793e4b809af608
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | snapvec-0.11.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 805.9 kB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
997533dd206379dabcffb151eab82b4373234f6eae87c0f5d83f980b0d75febb
|
|
BLAKE2b-256 checksum How to use checksums |
edcdd889b6f515da7575e3eaed9529bdbff5bb5143ece6fa804e9b842bfea477
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | snapvec-0.11.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 798.3 kB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
c87f1bb80355cb8c3bf65a3454b1e56012e14c86cf154965f3d9179758a92772
|
|
BLAKE2b-256 checksum How to use checksums |
141501a4a451b045f9413e139014c8dae11e52ee4b2cc8bca1af9768f44d8354
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | snapvec-0.11.1-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 530.0 kB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7e96041d0e4c31b6d7360cbcf773e9b6eb545d722ff4486af8571e65723b21ca
|
|
BLAKE2b-256 checksum How to use checksums |
e242d05cb8b8c26931a0ed412561dd1248eae3f3b5caab08c096a4b61cd3289c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp310-cp310-win_amd64.whl
| Download URL | snapvec-0.11.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 282.9 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
116231b3ce99c3e6ea7d7bcccb70c59bba4a0e01c1ae36f608e2fac8906a6090
|
|
BLAKE2b-256 checksum How to use checksums |
35be05050d47e04e8eecd692026c287173b8c71f0bb5cdc41ac7497240e289fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | snapvec-0.11.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 782.0 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
b82c3e271b77328029a1717234e373388b1ae903c0c7d1faa3afc131858da325
|
|
BLAKE2b-256 checksum How to use checksums |
405bf8a31472b63e8828649c960188d1727d0eea8e1b96d6df1d66a64de1ad33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | snapvec-0.11.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 770.1 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
cb22a4eac0a402ed796ebd37c56383ccfafc02f22f84cc1dea2c13f6762120a1
|
|
BLAKE2b-256 checksum How to use checksums |
fde59d80f8725cf76d204fc4f2090d580336e05baf887137154d910ea0c62162
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency logRelease files / snapvec-0.11.1-cp310-cp310-macosx_14_0_arm64.whl
| Download URL | snapvec-0.11.1-cp310-cp310-macosx_14_0_arm64.whl |
|---|---|
| Size | 530.3 kB |
| Tags | CPython 3.10 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
950d1e8c0dfadd90e43b892cf4f891a08fa828e7029105209aad318490d95943
|
|
BLAKE2b-256 checksum How to use checksums |
8009284a5a192fe60d689978f67dc538e5183e248d1b253d6d8a4fadd258132e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 22, 2026.
Transparency log
