Install & Compatibility
Where this runs
tested against v0.1.9 · 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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.022s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load
✓ from sqlite_vec import load
Used to load the sqlite-vec extension into a SQLite connection.
serialize_float32
✓ from sqlite_vec import serialize_float32
Helper function to convert Python list of floats into the compact BLOB format used by sqlite-vec.
This quickstart demonstrates how to initialize a SQLite database with the `sqlite-vec` extension, create a `vec0` virtual table for storing 4-dimensional float embeddings, insert example embeddings (using NumPy arrays, or `serialize_float32` for Python lists), and perform a K-Nearest Neighbors (KNN) search.
import sqlite3
from sqlite_vec import load, serialize_float32
import numpy as np # Often used for embeddings
import os
# Connect to an in-memory SQLite database
db = sqlite3.connect(":memory:")
# Enable loading of SQLite extensions (necessary for sqlite-vec)
db.enable_load_extension(True)
# Load the sqlite-vec extension
load(db)
# For security, disable extension loading immediately after loading
db.enable_load_extension(False)
# Verify the extension is loaded
vec_version, = db.execute("SELECT vec_version()").fetchone()
print(f"sqlite-vec version: {vec_version}")
# Create a virtual table for vectors using vec0 module
db.execute("CREATE VIRTUAL TABLE documents USING vec0(embedding float[4]);")
# Example embeddings (using numpy for convenience, ensure float32)
embedding1 = np.array([0.1, 0.2, 0.3, 0.4], dtype=np.float32)
embedding2 = np.array([0.5, 0.6, 0.7, 0.8], dtype=np.float32)
embedding3 = np.array([0.15, 0.25, 0.35, 0.45], dtype=np.float32)
# Insert embeddings into the virtual table
# sqlite-vec automatically handles numpy arrays if they implement the Buffer protocol
# For lists, use serialize_float32(list_of_floats)
db.execute("INSERT INTO documents(rowid, embedding) VALUES (?, ?);", (1, embedding1))
db.execute("INSERT INTO documents(rowid, embedding) VALUES (?, ?);", (2, embedding2))
db.execute("INSERT INTO documents(rowid, embedding) VALUES (?, ?);", (3, embedding3))
db.commit()
# Query for nearest neighbors (L2 distance by default)
query_embedding = np.array([0.1, 0.2, 0.3, 0.35], dtype=np.float32)
print("\nNearest neighbors to [0.1, 0.2, 0.3, 0.35]:")
for rowid, distance in db.execute(
"SELECT rowid, distance FROM documents WHERE embedding MATCH ? ORDER BY distance LIMIT 2;",
[query_embedding]
):
print(f"Document ID: {rowid}, Distance: {distance:.4f}")
# Close the database connection
db.close()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlite_vec'
The 'sqlite-vec' Python package has not been installed in the current Python environment.
fixInstall the package using pip: `pip install sqlite-vec`
sqlite3.OperationalError: unable to load extension: /path/to/sqlite_vec.so - No such file or directory
The SQLite database could not find the 'sqlite-vec' extension binary at the specified path, typically due to an incorrect path or the file not being present.
fixUse `sqlite_vec.loadable_path()` from the Python binding to ensure the correct, platform-specific path to the installed extension is used: `conn.load_extension(sqlite_vec.loadable_path())`
sqlite3.OperationalError: no such function: vec_version
The 'sqlite-vec' extension was not successfully loaded into the SQLite connection, so its SQL functions (like `vec_version()`) are unavailable.
fixEnsure `sqlite-vec` is correctly installed and loaded using `conn.load_extension(sqlite_vec.loadable_path())` before calling any `vec_` functions.
sqlite3.OperationalError: wrong number of arguments for function vec_distance()
The `vec_distance` SQL function was called with an incorrect number of arguments; it requires two vector blobs and a string specifying the distance metric.
fixProvide all three required arguments, for example: `SELECT vec_distance(X'00000000', X'01010101', 'L2');`
Upgrade
Version history
0.1.9latest on PyPI · released Mar 31, 2026
Audit
Dependencies
No dependency data recorded yet.