---
id: vecs
version: "0.4.5"
license: MIT
license_treatment: permissive
maintenance: aging
---

# vecs — pgvector client

License: permissive · Maintenance: aging · Downloads: 114.9K/mo

## What it is and what it does

vecs is a lightweight Python wrapper around PostgreSQL's pgvector extension, designed to simplify vector storage and retrieval operations. It provides a client interface for creating collections of vectors, upserting records with associated metadata, building indices for fast search, and querying with metadata filtering. The package handles the connection management and SQL generation needed to work with pgvector, abstracting away direct database interaction.

The package is intended for developers building semantic search, similarity matching, or embedding-based applications on top of PostgreSQL. It requires an existing PostgreSQL instance with pgvector already installed—there is no embedded database or managed service bundled with the package itself. Use it when you have vector data to store alongside relational data and want to leverage PostgreSQL's existing infrastructure rather than adopting a separate vector database.

Use it for:

- Build semantic search over documents by storing embeddings and querying with similarity filters.
- Implement recommendation systems by storing user/item embeddings and finding nearest neighbors.
- Add vector similarity matching to existing PostgreSQL applications without migrating to a specialized vector store.
- Query embeddings with metadata constraints, e.g., find similar vectors only from a specific time period or category.
- Prototype vector search workflows before committing to a dedicated vector database.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

vecs is a Python client for storing, indexing, and querying vectors in PostgreSQL using the pgvector extension, enabling semantic search and similarity operations on vector data.

Yes, if you already operate PostgreSQL with pgvector and need a Python interface to vector operations. The permissive MIT license and lack of runtime dependencies make it low-friction to add to an existing stack. However, the aging maintenance status (last commit 2025-04-09, no releases since 2024-12-13) and high install friction (requires external database setup) mean this is best suited for teams with PostgreSQL expertise and a clear need to keep vectors in relational storage. Not a good choice if you need active development support or are evaluating vector databases from scratch.

## Install

pip install vecs
uv add vecs
poetry add vecs

## Installing vecs

Before you install: Installation friction is high: the package itself has no runtime dependencies, but requires an external PostgreSQL database with pgvector extension already configured and accessible. The project shows aging maintenance status with the last commit on 2025-04-09 and no releases since 2024-12-13, though the repository remains active and not archived.

License in practice: MIT license permits commercial and private use with minimal restrictions, making it suitable for most projects. You must include the license text in distributions.

Quickstart:

pip install vecs

import vecs
vx = vecs.create_client("postgresql://:@:/<db_name>")
docs = vx.get_or_create_collection(name="docs", dimension=3)
docs.upsert(records=[("id", [0.1, 0.2, 0.3], {"meta": "data"})])
results = docs.query(data=[0.4, 0.5, 0.6], limit=1)

Requires a PostgreSQL database with pgvector extension already installed and running, plus a valid connection string to access it.

Verify before relying:

- Whether the aging maintenance status (last commit 2025-04-09, no releases since 2024-12-13) indicates active development or stalled support.
- Performance characteristics and scalability limits for large vector collections.
- Compatibility with recent pgvector versions and PostgreSQL releases.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: high
- Maintenance: aging
- Downloads: 114.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

postgresql vector search client, pgvector python wrapper, vector database management, semantic search postgres, vector similarity queries, embedding storage postgres, vector indexing client, vector-search, postgresql, embeddings

[View on SkillFed](https://skillfed.io/packages/vecs) · [View on PyPI](https://pypi.org/project/vecs/)