{"id":6293,"library":"usearch","title":"USearch Vector Search Engine","description":"USearch is a smaller and faster single-file vector search engine from Unum, offering high-performance approximate nearest neighbor search. It is compact and broadly compatible, focusing on user-defined metrics and fewer dependencies. It follows a rapid release cadence, often with monthly or bi-monthly updates, incorporating bug fixes, performance improvements, and new language bindings across its C++, Python, JavaScript, Rust, Java, Objective-C, Swift, C#, GoLang, and Wolfram APIs.","status":"active","version":"2.24.0","language":"en","source_language":"en","source_url":"https://github.com/unum-cloud/USearch","tags":["vector-search","embeddings","similarity-search","ann","high-performance","faiss-alternative"],"install":[{"cmd":"pip install usearch numpy","lang":"bash","label":"Install with NumPy"}],"dependencies":[{"reason":"Commonly used for vector operations in Python with USearch; quickstart examples utilize it. While not strictly an 'obligatory dependency' for the core C++ library, it is practically required for Python usage.","package":"numpy","optional":false}],"imports":[{"symbol":"Index","correct":"from usearch.index import Index"},{"symbol":"Matches","correct":"from usearch.index import Matches"}],"quickstart":{"code":"import numpy as np\nfrom usearch.index import Index, Matches\n\n# Initialize an index for 3-dimensional vectors using cosine similarity\nindex = Index(\n    ndim=3,\n    metric='cos', # Options include 'l2sq', 'haversine', 'ip' (inner product)\n    dtype='f32',  # Quantization to 'f16' (half-precision) or 'i8' (int8) for efficiency\n    connectivity=16,\n    expansion_add=128,\n    expansion_search=64\n)\n\n# Create some example vectors\nvector1 = np.array([0.2, 0.6, 0.4], dtype=np.float32)\nvector2 = np.array([0.1, 0.7, 0.3], dtype=np.float32)\nvector3 = np.array([0.9, 0.1, 0.5], dtype=np.float32)\n\n# Add vectors to the index with unique keys\nindex.add(key=42, vector=vector1)\nindex.add(key=43, vector=vector2)\nindex.add(key=44, vector=vector3)\n\nprint(f\"Index contains {len(index)} vectors.\")\n\n# Query the index for the 2 nearest neighbors of vector1\nquery_vector = np.array([0.21, 0.61, 0.41], dtype=np.float32)\nmatches: Matches = index.search(query_vector, 2)\n\nprint(f\"Found {len(matches)} matches for the query:\")\nfor i, match in enumerate(matches):\n    print(f\"  Match {i+1}: Key={match.key}, Distance={match.distance:.4f}\")\n\n# Access a vector by key\nretrieved_vector = index[42]\nprint(f\"Retrieved vector for key 42: {retrieved_vector}\")\nassert np.allclose(retrieved_vector, vector1)","lang":"python","description":"This quickstart demonstrates how to initialize a USearch index, add vectors with keys, perform a similarity search to find nearest neighbors, and retrieve vectors by their keys. It uses `numpy` for vector creation and manipulation."},"warnings":[{"fix":"Ensure you are on the latest stable version of USearch. For critical concurrent writes, review release notes and consider sequential operations or implementing custom synchronization mechanisms if issues persist.","message":"Earlier versions of USearch (e.g., around v2.21.x) exhibited race conditions and bugs related to concurrent `add()` and `update()` operations, potentially leading to unreachable nodes in the graph or integer underflows. While some fixes were applied (v2.21.2, v2.21.4), new issues like 'Concurrent add() creates nodes unreachable by search()' can still occur, indicating ongoing development for full concurrent stability.","severity":"gotcha","affected_versions":"<=2.21.x, potentially others"},{"fix":"For performance-critical user-defined metrics, consider JIT compilation using libraries like Numba or integrating C/C++ functions via `cppyy` to compile and pass native code to the USearch engine.","message":"While USearch supports user-defined metrics, passing Python callable functions directly to the engine for distance calculations can incur a performance penalty due to Python's Global Interpreter Lock (GIL) and language boundary overhead.","severity":"gotcha","affected_versions":"All versions (inherent to Python bindings)"},{"fix":"Upgrade to USearch v2.23.0 or newer to ensure compatibility and full support for Python 3.14 and subsequent versions.","message":"Python 3.14 support was explicitly added in USearch v2.23.0. Users of Python 3.14 (or newer pre-release versions) attempting to use USearch versions older than 2.23.0 may encounter compatibility issues or unexpected behavior.","severity":"breaking","affected_versions":"<2.23.0"},{"fix":"For applications requiring absolute reproducibility, consider fixing the environment (OS, compiler, library versions) and carefully testing. Understand that minor variations in distances are generally expected within numerical tolerance for Approximate Nearest Neighbor (ANN) search.","message":"Results from high-performance numerical libraries like USearch can occasionally show minor differences across different operating systems, compilers, or even between runs on the same system. This is typically due to subtle variations in floating-point arithmetic rounding errors and tie-breaking algorithms, which are often non-deterministic across different environments.","severity":"gotcha","affected_versions":"All versions (inherent to numerical computation)"},{"fix":"Always use the latest stable version of USearch, especially if encountering platform-specific issues or compilation errors, as these are actively addressed in ongoing releases.","message":"Specific platform-dependent fixes (e.g., `mmap` flags for FreeBSD, compilation errors in Qt environments, Pearson correlation negative denominator fix) are frequently rolled into minor releases. Users operating on less common environments or specific setups might encounter subtle bugs or compilation issues with slightly older USearch versions.","severity":"gotcha","affected_versions":"Versions before 2.24.0 (for specific platform fixes)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}