Removed dependency on NumPy [skip ci]

ankane · ankane · commit 66bac991084b · 2026-06-02T17:05:35.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 - Changed `vector` type to return `Vector` object instead of NumPy array
 - Removed `utils` package (use top-level `pgvector` package instead)
 - Removed re-exported classes (use top-level `pgvector` package instead)
+- Removed dependency on NumPy
 - Dropped support for Python < 3.10
 - Dropped support for SQLAlchemy < 2
 
diff --git a/pgvector/bit.py b/pgvector/bit.py
@@ -1,5 +1,4 @@
 from __future__ import annotations
-import numpy as np
 from struct import pack, unpack_from
 from warnings import warn
 
@@ -13,6 +12,8 @@ def __init__(self, value: bytes | str | list[bool] | np.ndarray[tuple[int], np.d
             if isinstance(value, str):
                 value = [v != '0' for v in value]
             else:
+                import numpy as np
+
                 value = np.asarray(value)
 
                 # for mypy
diff --git a/pgvector/halfvec.py b/pgvector/halfvec.py
@@ -1,7 +1,11 @@
 from __future__ import annotations
-import numpy as np
 import struct
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 class HalfVector:
     def __init__(self, value: list[float] | np.ndarray[tuple[int], np.dtype[np.floating]]) -> None:
@@ -11,7 +15,7 @@ def __init__(self, value: list[float] | np.ndarray[tuple[int], np.dtype[np.float
                 self._value = struct.pack(f'>HH{dim}e', dim, 0, *value)
             except struct.error:
                 raise ValueError('expected list[float]')
-        elif isinstance(value, np.ndarray):
+        elif np is not None and isinstance(value, np.ndarray):
             if value.ndim != 1:
                 raise ValueError('expected ndim to be 1')
 
diff --git a/pgvector/pg8000/register.py b/pgvector/pg8000/register.py
@@ -1,7 +1,11 @@
-import numpy as np
 from pg8000.native import Connection
 from .. import Vector, HalfVector, SparseVector
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 def register_vector(conn: Connection) -> None:
     # use to_regtype to get first matching type in search path
@@ -12,7 +16,8 @@ def register_vector(conn: Connection) -> None:
         raise RuntimeError('vector type not found in the database')
 
     conn.register_out_adapter(Vector, Vector._to_db)
-    conn.register_out_adapter(np.ndarray, Vector._to_db)
+    if np is not None:
+        conn.register_out_adapter(np.ndarray, Vector._to_db)
     conn.register_in_adapter(type_info['vector'], Vector._from_db)
 
     if 'halfvec' in type_info:
diff --git a/pgvector/psycopg/vector.py b/pgvector/psycopg/vector.py
@@ -1,4 +1,3 @@
-import numpy as np
 import psycopg
 from psycopg import BaseConnection
 from psycopg.adapt import Loader, Dumper
diff --git a/pgvector/psycopg2/vector.py b/pgvector/psycopg2/vector.py
@@ -1,7 +1,11 @@
-import numpy as np
 from psycopg2.extensions import adapt, connection, cursor, new_array_type, new_type, register_adapter, register_type
 from .. import Vector
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 class VectorAdapter:
     def __init__(self, value: object) -> None:
@@ -23,5 +27,6 @@ def register_vector_info(oid: int, array_oid: int | None, scope: connection | cu
         vectorarray = new_array_type((array_oid,), 'VECTORARRAY', vector)
         register_type(vectorarray, scope)
 
-    register_adapter(np.ndarray, VectorAdapter)
+    if np is not None:
+        register_adapter(np.ndarray, VectorAdapter)
     register_adapter(Vector, VectorAdapter)
diff --git a/pgvector/sparsevec.py b/pgvector/sparsevec.py
@@ -1,8 +1,12 @@
 from __future__ import annotations
-import numpy as np
 from struct import pack, unpack_from
 from typing import Any, overload
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 NO_DEFAULT = object()
 
 
diff --git a/pgvector/vector.py b/pgvector/vector.py
@@ -1,7 +1,11 @@
 from __future__ import annotations
-import numpy as np
 import struct
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 class Vector:
     def __init__(self, value: list[float] | np.ndarray[tuple[int], np.dtype[np.floating]]) -> None:
@@ -11,7 +15,7 @@ def __init__(self, value: list[float] | np.ndarray[tuple[int], np.dtype[np.float
                 self._value = struct.pack(f'>HH{dim}f', dim, 0, *value)
             except struct.error:
                 raise ValueError('expected list[float]')
-        elif isinstance(value, np.ndarray):
+        elif np is not None and isinstance(value, np.ndarray):
             if value.ndim != 1:
                 raise ValueError('expected ndim to be 1')
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -13,7 +13,6 @@ authors = [
 license = "MIT"
 requires-python = ">= 3.10"
 dependencies = [
-    "numpy"
 ]
 
 [project.urls]
@@ -29,10 +28,13 @@ dev = [
     "psycopg2-binary",
     "pytest",
     "pytest-asyncio",
-    "scipy",
     "SQLAlchemy[asyncio]>=2",
     "sqlmodel>=0.0.12"
 ]
+dev2 = [
+    "numpy",
+    "scipy"
+]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
diff --git a/tests/test_asyncpg.py b/tests/test_asyncpg.py
@@ -1,5 +1,4 @@
 import asyncpg
-import numpy as np
 from pgvector import HalfVector, SparseVector, Vector
 from pgvector.asyncpg import register_vector
 import pytest
@@ -16,7 +15,7 @@ async def test_vector(self):
         await register_vector(conn)
 
         embedding = Vector([1.5, 2, 3])
-        embedding2 = np.array([4.5, 5, 6])
+        embedding2 = [4.5, 5, 6]
         await conn.execute("INSERT INTO asyncpg_items (embedding) VALUES ($1), ($2), (NULL)", embedding, embedding2)
 
         res = await conn.fetch("SELECT * FROM asyncpg_items ORDER BY id")
@@ -111,7 +110,7 @@ async def test_vector_array(self):
         embeddings = [Vector([1.5, 2, 3]), Vector([4.5, 5, 6])]
         await conn.execute("INSERT INTO asyncpg_items (embeddings) VALUES ($1)", embeddings)
 
-        embeddings2 = [np.array([1.5, 2, 3]), np.array([4.5, 5, 6])]
+        embeddings2 = [[1.5, 2, 3], [4.5, 5, 6]]
         await conn.execute("INSERT INTO asyncpg_items (embeddings) VALUES (ARRAY[$1, $2]::vector[])", embeddings2[0], embeddings2[1])
 
         res = await conn.fetch("SELECT * FROM asyncpg_items ORDER BY id")
@@ -133,7 +132,7 @@ async def init(conn):
             await conn.execute('CREATE TABLE asyncpg_items (id bigserial PRIMARY KEY, embedding vector(3))')
 
             embedding = Vector([1.5, 2, 3])
-            embedding2 = np.array([1.5, 2, 3])
+            embedding2 = [1.5, 2, 3]
             await conn.execute("INSERT INTO asyncpg_items (embedding) VALUES ($1), ($2), (NULL)", embedding, embedding2)
 
             res = await conn.fetch("SELECT * FROM asyncpg_items ORDER BY id")
diff --git a/tests/test_bit.py b/tests/test_bit.py
@@ -1,7 +1,11 @@
-import numpy as np
 from pgvector import Bit
 import pytest
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 class TestBit:
     def test_list(self):
@@ -22,20 +26,24 @@ def test_bytes(self):
         assert Bit(b'\xff\x00\xf0').to_text() == '111111110000000011110000'
         assert Bit(b'\xfe\x07\x00').to_text() == '111111100000011100000000'
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_ndarray(self):
         arr = np.array([True, False, True])
         assert Bit(arr).to_list() == [True, False, True]
         assert np.array_equal(Bit(arr).to_numpy(), arr)
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_ndarray_unpackbits(self):
         arr = np.unpackbits(np.array([254, 7, 0], dtype=np.uint8))
         assert Bit(arr).to_text() == '111111100000011100000000'
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_ndarray_uint8(self):
         arr = np.array([254, 7, 0], dtype=np.uint8)
         with pytest.warns(UserWarning, match='expected elements to be boolean'):
             assert Bit(arr).to_text() == '110'
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_ndarray_uint16(self):
         arr = np.array([254, 7, 0], dtype=np.uint16)
         with pytest.warns(UserWarning, match='expected elements to be boolean'):
diff --git a/tests/test_django.py b/tests/test_django.py
@@ -11,13 +11,17 @@
 from django.db.migrations.loader import MigrationLoader
 from django.forms import ModelForm
 from math import sqrt
-import numpy as np
 import os
 import pgvector.django
 from pgvector import HalfVector, SparseVector, Vector
 from pgvector.django import VectorExtension, VectorField, HalfVectorField, BitField, SparseVectorField, IvfflatIndex, HnswIndex, L2Distance, MaxInnerProduct, CosineDistance, L1Distance, HammingDistance, JaccardDistance
 from unittest import mock
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 settings.configure(
     DATABASES={
         'default': {
@@ -458,7 +462,7 @@ def test_missing(self):
         assert Item.objects.first().sparse_embedding is None
 
     def test_vector_array(self):
-        Item(id=1, embeddings=[np.array([1, 2, 3]), np.array([4, 5, 6])]).save()
+        Item(id=1, embeddings=[Vector([1, 2, 3]), Vector([4, 5, 6])]).save()
 
         with connection.cursor() as cursor:
             from pgvector.psycopg import register_vector
diff --git a/tests/test_half_vector.py b/tests/test_half_vector.py
@@ -1,8 +1,12 @@
-import numpy as np
 from pgvector import HalfVector
 import pytest
 from struct import pack
 
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
 
 class TestHalfVector:
     def test_list(self):
@@ -21,6 +25,7 @@ def test_list_list(self):
             HalfVector([[1, 2], [3, 4]])  # ty: ignore[invalid-argument-type]
         assert str(error.value) == 'expected list[float]'
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_ndarray(self):
         arr = np.array([1, 2, 3])
         assert HalfVector(arr).to_list() == [1, 2, 3]
@@ -42,6 +47,7 @@ def test_equality(self):
     def test_dimensions(self):
         assert HalfVector([1, 2, 3]).dimensions() == 3
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_to_numpy_readonly(self):
         arr = HalfVector([1, 2, 3]).to_numpy()
         with pytest.raises(ValueError) as error:
@@ -51,11 +57,13 @@ def test_to_numpy_readonly(self):
     def test_from_text(self):
         vec = HalfVector.from_text('[1.5,2,3]')
         assert vec.to_list() == [1.5, 2, 3]
-        assert np.array_equal(vec.to_numpy(), [1.5, 2, 3])
+        if np is not None:
+            assert np.array_equal(vec.to_numpy(), [1.5, 2, 3])
 
     def test_from_binary(self):
         data = pack('>HH3e', 3, 0, 1.5, 2, 3)
         vec = HalfVector.from_binary(data)
         assert vec.to_list() == [1.5, 2, 3]
-        assert np.array_equal(vec.to_numpy(), [1.5, 2, 3])
+        if np is not None:
+            assert np.array_equal(vec.to_numpy(), [1.5, 2, 3])
         assert vec.to_binary() == data
diff --git a/tests/test_peewee.py b/tests/test_peewee.py
@@ -1,5 +1,4 @@
 from math import sqrt
-import numpy as np
 from peewee import Model, PostgresqlDatabase, fn
 from pgvector import HalfVector, SparseVector, Vector
 from pgvector.peewee import VectorField, HalfVectorField, FixedBitField, SparseVectorField
@@ -197,7 +196,7 @@ def test_halfvec_sum(self):
 
     def test_get_or_create(self):
         Item.get_or_create(id=1, defaults={'embedding': [1, 2, 3]})
-        Item.get_or_create(embedding=np.array([4, 5, 6]))
+        Item.get_or_create(embedding=Vector([4, 5, 6]))
         Item.get_or_create(embedding=Item.embedding.to_value([7, 8, 9]))
 
     def test_vector_array(self):
diff --git a/tests/test_pg8000.py b/tests/test_pg8000.py
@@ -1,8 +1,13 @@
 from getpass import getuser
-import numpy as np
 from pgvector import HalfVector, SparseVector, Vector
 from pgvector.pg8000 import register_vector
 from pg8000.native import Connection
+import pytest
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
 
 conn = Connection(getuser(), database='pgvector_python_test')
 
@@ -17,6 +22,7 @@ class TestPg8000:
     def setup_method(self):
         conn.run('DELETE FROM pg8000_items')
 
+    @pytest.mark.skipif(np is None, reason='NumPy required')
     def test_vector(self):
         embedding = np.array([1.5, 2, 3])
         conn.run('INSERT INTO pg8000_items (embedding) VALUES (:embedding), (NULL)', embedding=embedding)
diff --git a/tests/test_psycopg.py b/tests/test_psycopg.py
diff --git a/tests/test_psycopg2.py b/tests/test_psycopg2.py
diff --git a/tests/test_sparse_vector.py b/tests/test_sparse_vector.py
diff --git a/tests/test_sqlalchemy.py b/tests/test_sqlalchemy.py
diff --git a/tests/test_sqlmodel.py b/tests/test_sqlmodel.py
diff --git a/tests/test_vector.py b/tests/test_vector.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-import numpy as np`
`2`	`1`	`import psycopg`
`3`	`2`	`from psycopg import BaseConnection`
`4`	`3`	`from psycopg.adapt import Loader, Dumper`