Install & Compatibility
Where this runs
tested against v0.4.5 · 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 1.248s · 124.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.9s · import 1.204s · 121MB
126MB installed
● package 126MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import vecs
The main object is 'vecs.Client', not 'vecs.client' or 'vecs.Vecs'.
Collection
✓ from vecs import Collection
Collection is a class used for managing vector collections.
Connect to a Supabase Postgres instance with pgvector, create a collection, upsert vectors, and query.
import vecs
DB_CONNECTION = "postgresql://user:pass@host:5432/db"
vx = vecs.Client(DB_CONNECTION)
# Create a collection of vectors with 384 dimensions
docs = vx.create_collection(name="docs", dimension=384)
# Add vectors
docs.upsert(
records=[
("vec0", [0.1, 0.2, ...], {"key": "val"}), # truncated for brevity
("vec1", [0.3, 0.4, ...], {}),
]
)
docs.create_index()
# Query
results = docs.query(
data=[0.1, 0.2, ...],
limit=5,
filters={"key": {"$eq": "val"}}
)
print(results)
Debug
Known issues
breakingThe library changed from using 'vecs.Client' to 'vecs.Client' (no change) but the underlying API for creating collections changed from 'create_collection' to the current pattern. Old code using 'vecs.client' (lowercase) or 'vecs.create_client' will fail.fixUse 'import vecs; vx = vecs.Client(DB_CONNECTION)'.
affects: <=0.3.x vs 0.4.x
gotchaThe 'upsert' method expects records as a list of tuples: (id, vector, metadata). The vector must be a list of floats. Passing numpy arrays may cause issues.fixConvert numpy arrays to list: vector.tolist().
affects: all
gotchaCreating an index with 'create_index()' is not automatic; you must call it after upserting data for good performance. Default index is IVFFlat with no parameters; consider specifying index type and parameters.fixUse 'docs.create_index(measure=vecs.IndexMeasure.cosine_distance, index=vecs.IndexMethod.ivfflat, params=dict(lists=100))'.
affects: all
deprecatedThe method 'upsert_docs' and 'query_docs' have been removed. Use 'upsert' and 'query'.fixReplace 'upsert_docs' with 'upsert' and 'query_docs' with 'query'.
affects: >=0.4.0
gotchaThe 'query' method returns a list of tuples (id, distance, metadata). The distance is the actual distance, not similarity. For cosine distance, lower is better.fixCheck the distance metric used when interpreting results.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vecs'
vecs is not installed or installed in a different environment.
fixRun 'pip install vecs' and ensure you are using the correct Python environment.
TypeError: Client() takes 1 positional argument but 2 were given
Old code using 'vecs.Client(DB_CONNECTION)' used to allow an extra argument or the import pattern changed.
fixUse 'vx = vecs.Client(DB_CONNECTION)' without additional arguments.
AttributeError: module 'vecs' has no attribute 'client'
Trying to access lowercase 'vecs.client' instead of 'vecs.Client'.
fixUse 'vecs.Client' with capital C.
psycopg2.errors.UndefinedObject: type "vector" does not exist
The PostgreSQL extension 'vector' (pgvector) is not installed in the database.
fixRun 'CREATE EXTENSION vector;' in the PostgreSQL database.
Upgrade
Version history
0.4.5latest on PyPI · released Dec 13, 2024
Audit
Dependencies
No dependency data recorded yet.