Install & Compatibility
Where this runs
tested against v6.5.16 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
simsimd
✓ import simsimd
Functions are directly available on the imported `simsimd` module, e.g., `simsimd.cosine()` or `simsimd.cdist()`.
This example demonstrates how to calculate various vector similarity metrics (cosine, squared Euclidean, inner product) between two NumPy arrays using SimSIMD. Ensure NumPy is installed as it's commonly used for array creation, although not a direct dependency of SimSIMD.
import simsimd
import numpy as np
# Create two random 1536-dimensional vectors for demonstration
vec1 = np.random.randn(1536).astype(np.float32)
vec2 = np.random.randn(1536).astype(np.float32)
# Calculate cosine similarity
distance = simsimd.cosine(vec1, vec2)
print(f"Cosine distance: {distance}")
# Calculate squared Euclidean distance
distance_sqeuclidean = simsimd.sqeuclidean(vec1, vec2)
print(f"Squared Euclidean distance: {distance_sqeuclidean}")
# Calculate inner product
inner_product = simsimd.inner(vec1, vec2)
print(f"Inner product: {inner_product}")
Debug
Known issues
breakingThe project `simsimd` has been renamed to `NumKong` starting from its major version 7.x.x. While `simsimd` 6.5.16 is available on PyPI, users seeking the latest features and fixes (v7.x.x) should refer to `NumKong`. This change introduces significant breaking API changes, including function renames (e.g., 'cosine' to 'angular') and altered data structures.fixFor new projects or major upgrades, consider migrating to `NumKong` and carefully review its documentation for updated API calls and data types. For existing `simsimd` 6.x.x projects, remain on the `simsimd` package or plan a full migration.
affects: All versions migrating from `simsimd` (any 6.x.x) to `NumKong` (7.x.x and later)
gotchaOlder versions of `simsimd` (pre-v7.3.0 on GitHub, which corresponds to versions prior to the latest PyPI release `6.5.16`) contained a correctness bug in Arm Scalable Vector Extension (SVE) kernels. Specifically, `_x` (don't-care) predicated intrinsics could carry stale data, leading to incorrect results for non-power-of-two dimensions on real SVE hardware.fixUpgrade to the latest available version of `simsimd` or `NumKong` to benefit from the corrected Arm SVE kernels, especially if deploying on Arm-based systems with SVE support.
affects: < 7.3.0 (GitHub releases); potentially `6.5.16` and earlier on PyPI if not backported.
gotchaWhen installing `simsimd` from source (i.e., when pre-built wheels are not available for your environment), older versions sometimes encountered a `FileNotFoundError: 'VERSION'` error during the build process. This issue was related to how the version was read during `pip install .` without wheels.fixEnsure `pip` is up-to-date. If encountering this, try installing a specific known-working version (e.g., `5.5.1` as a historical workaround) or ensure your environment can use pre-built wheels. Cloning the repository and installing with `pip install .` might also be a workaround if the version file exists in the cloned repo. For current versions, this should be resolved by the use of `pyproject.toml`.
affects: Specific older versions like `5.6.0`, potentially others without pre-built wheels.
Upgrade
Version history
6.5.16latest on PyPI · released Mar 7, 2026
Audit
Dependencies
No dependency data recorded yet.