Installation#

The driver is published on PyPI as agensgraph-python and imported as agensgraph.

$ pip install agensgraph-python

It brings three dependencies with it: psycopg 3 with its binary build (psycopg[binary] 3.3.4 or later), psycopg-pool 3.3.1 or later, and msgspec, which encodes and decodes property maps.

Requirements#


Python	3.11, 3.12, 3.13 or 3.14
AgensGraph	2.17 or later
pgvector	only for embedding vectors, created in the database you use

The server is checked when you connect. AgensGraph reports its version in the first packet of the connection, so a server older than 2.17 is refused before any statement is sent, with a message naming both versions. Compatibility lists what each server line supports.

Optional extras#

Four features need a library the driver does not install by default. Each is imported only by the function that needs it, so an extra you do not install costs nothing, and one you do install is never loaded on an ordinary query.

$ pip install "agensgraph-python[arrow]"     # Arrow tables and record batches
$ pip install "agensgraph-python[pandas]"    # pandas DataFrames
$ pip install "agensgraph-python[polars]"    # polars DataFrames
$ pip install "agensgraph-python[otel]"      # OpenTelemetry spans

Extra	Installs	Used by
`arrow`	`pyarrow` 17 or later	`to_arrow`, `batches`, `reader`, `load_vertex_frame`, `load_edge_frame`
`pandas`	`pandas` 2.2 or later	`to_pandas`, together with `arrow`
`polars`	`polars` 1.0 or later	`to_polars`, together with `arrow`
`otel`	`opentelemetry-api` 1.33 or later	`enable_tracing`

to_pandas and to_polars build an Arrow table first, so install arrow with either. Extras combine: pip install "agensgraph-python[arrow,pandas]".

Check the installation#

$ python -c "import agensgraph; print(agensgraph.__version__)"
2.0.0

Then connect to a server. Replace the connection string with your own; it takes the same keywords as psql and every other libpq client:

import agensgraph

with agensgraph.connect("host=localhost dbname=docs user=agens") as conn:
    print(conn.capabilities.reported)

2.18.6.0

capabilities.reported is the version string the server sent. If this prints, the driver can read that server.

Install from source#

The source is on GitHub. Each release is a tag, v2.0.0 for this one, and the wheel and source distribution are attached to the GitHub release as well as published on PyPI.

$ git clone https://github.com/skaiworldwide-oss/agensgraph-python
$ cd agensgraph-python
$ pip install .

The package is pure Python, so there is nothing to compile.