{"id":60,"library":"pgvector","title":"pgvector","description":"Open-source PostgreSQL extension for vector similarity search. Two components: (1) the server-side Postgres extension (C, compiled and installed into Postgres), and (2) the Python client package 'pgvector' on PyPI which provides ORM/adapter integrations for psycopg2, psycopg3, asyncpg, SQLAlchemy, Django, SQLModel, and Peewee. The extension name in SQL is 'vector' (CREATE EXTENSION vector), not 'pgvector'. Maintained by Andrew Kane. Current extension version: 0.8.2 (CVE security fix). Python client: 0.4.2.","status":"active","version":"0.8.2","language":"python","source_language":"en","source_url":"https://github.com/pgvector/pgvector","tags":["pgvector","postgres","postgresql","vector-search","similarity-search","embeddings","hnsw","ivfflat","rag","sql"],"install":[{"cmd":"pip install pgvector","lang":"bash","label":"Python client (ORM integrations)"},{"cmd":"sudo apt install postgresql-17-pgvector","lang":"bash","label":"Ubuntu/Debian (APT, replace 17 with your PG version)"},{"cmd":"brew install pgvector","lang":"bash","label":"macOS via Homebrew"},{"cmd":"docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass pgvector/pgvector:pg17","lang":"bash","label":"Docker (official image)"},{"cmd":"git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git && cd pgvector && make && make install","lang":"bash","label":"Build from source (requires pg dev headers)"}],"dependencies":[{"reason":"Required. pgvector Python package is adapter-only — you must separately install a Postgres driver. psycopg2-binary for sync, psycopg (psycopg3) for async/LangChain.","package":"psycopg2 or psycopg3 or asyncpg","optional":false},{"reason":"Required when passing vectors as arrays. pgvector accepts Python lists or numpy float32 arrays.","package":"numpy","optional":false}],"imports":[{"wrong":"from pgvector.psycopg2 import register_vector","symbol":"Vector","correct":"from pgvector import Vector"},{"symbol":"HalfVector","correct":"from pgvector import HalfVector"},{"symbol":"SparseVector","correct":"from pgvector import SparseVector"}],"quickstart":{"code":"# Step 1: Enable extension in Postgres (run once per database)\n# CREATE EXTENSION IF NOT EXISTS vector;\n\nimport psycopg2\nfrom pgvector.psycopg2 import register_vector\nimport numpy as np\n\nconn = psycopg2.connect(\"dbname=mydb user=postgres\")\nregister_vector(conn)  # REQUIRED: registers the vector type\n\ncur = conn.cursor()\ncur.execute(\"CREATE TABLE IF NOT EXISTS items (id bigserial PRIMARY KEY, embedding vector(3))\")\n\n# Insert vectors\ncur.execute(\"INSERT INTO items (embedding) VALUES (%s)\", (np.array([1.0, 2.0, 3.0], dtype='float32'),))\nconn.commit()\n\n# L2 distance search (<->)\ncur.execute(\"SELECT id FROM items ORDER BY embedding <-> %s LIMIT 5\", (np.array([1.0, 1.0, 1.0], dtype='float32'),))\nprint(cur.fetchall())\n\ncur.close()\nconn.close()","lang":"python","description":"register_vector(conn) must be called after connecting — it registers the custom 'vector' type with psycopg2. Without it, vectors are returned as strings. Extension must be enabled server-side first with CREATE EXTENSION vector."},"warnings":[{"fix":"Upgrade to pgvector 0.8.2 immediately.","message":"CVE-2026-3172: Buffer overflow with parallel HNSW index builds in versions 0.6.0–0.8.1. Can leak sensitive data from other relations or crash the database server. Fixed in 0.8.2.","severity":"breaking","affected_versions":"0.6.0 to 0.8.1"},{"fix":"Report to your cloud provider. If self-hosting, compile on the same CPU architecture as the runtime. Cannot be worked around from the client side.","message":"Illegal instruction crashes (SIGILL) when pgvector is compiled with -march=native on one CPU architecture and run on another. Occurs on managed cloud Postgres (Azure Flexible Server, some GCP instances) after upgrading to 0.8.0+.","severity":"breaking","affected_versions":"0.8.0+"},{"fix":"pip install psycopg[binary]. Use connection string postgresql+psycopg://user:pass@host/db.","message":"LangChain's langchain-postgres package requires psycopg3 (package name: psycopg). Connection strings must use postgresql+psycopg:// not postgresql+psycopg2://. Mixing drivers causes driver-not-found errors.","severity":"breaking","affected_versions":"all"},{"fix":"Upgrade to Postgres 17.3+.","message":"Postgres 17.0–17.2 causes link error: 'unresolved external symbol float_to_shortest_decimal_bufn' when building pgvector from source.","severity":"breaking","affected_versions":"all source builds against PG 17.0-17.2"},{"fix":"Always use: CREATE EXTENSION IF NOT EXISTS vector;","message":"The SQL extension name is 'vector', not 'pgvector'. CREATE EXTENSION pgvector raises 'extension not found'. This is a consistent source of confusion.","severity":"gotcha","affected_versions":"all"},{"fix":"Call register_vector(conn) immediately after psycopg2.connect(). For connection pools, call it in the connection setup callback.","message":"register_vector(conn) must be called after every new connection. It is not persistent. Failing to call it means vector columns are returned as raw strings, not numpy arrays. No error is raised — silent wrong behavior.","severity":"gotcha","affected_versions":"all (psycopg2)"},{"fix":"Always include ORDER BY embedding <-> $1 LIMIT k in vector search queries. Without LIMIT, the index is not used.","message":"HNSW and IVFFlat indexes without ORDER BY + LIMIT do not use the ANN index — Postgres falls back to sequential scan. Queries without LIMIT return exact results but at O(n) cost.","severity":"gotcha","affected_versions":"all"},{"fix":"Use pgvector cosine thresholds in [0, 2]. Equivalent: pgvector_threshold = 1 - cosine_similarity.","message":"COSINE distance in pgvector uses the range [0, 2], not [0, 1]. 0 = identical, 2 = opposite. Thresholds from other libraries (which use [0,1]) must be remapped.","severity":"gotcha","affected_versions":"all"},{"fix":"Load all or most data first, then run CREATE INDEX. For ongoing ingestion, rebuild or use HNSW which handles incremental inserts better.","message":"IVFFlat index must be built AFTER data is loaded. Creating the index on an empty table and then inserting data results in a near-useless index (lists are not representative of the data distribution).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.4.2':73 '0.8.2':67 '1':13 '2':27 'andrew':62 'asyncpg':42 'c':20 'client':30,72 'compil':21 'compon':12 'creat':55 'current':64 'cve':68 'django':44 'embed':83 'extens':6,19,49,56,65 'fix':70 'hnsw':84 'instal':23 'integr':38 'ivfflat':85 'kane':63 'maintain':60 'name':50 'open':3 'open-sourc':2 'orm/adapter':37 'packag':31 'peewe':47 'pgvector':1,32,59,74 'postgr':18,25,75 'postgresql':5,76 'provid':36 'psycopg2':40 'psycopg3':41 'pypi':34 'python':29,71 'rag':86 'search':10,79,82 'secur':69 'server':16 'server-sid':15 'side':17 'similar':9,81 'similarity-search':80 'sourc':4 'sql':52,87 'sqlalchemi':43 'sqlmodel':45 'two':11 'vector':8,54,57,78 'vector-search':77 'version':66","created_at":"2026-03-16T04:39:09.011572+00:00","updated_at":"2026-04-16T17:59:42.577280+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.4.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://pgvector.io","github":"https://github.com/pgvector/pgvector-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pgvector/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["vector-search","database","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"stale"}}