# Installation

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

```console
$ pip install agensgraph-python
```

It brings three dependencies with it: [psycopg 3](https://www.psycopg.org/psycopg3/) with its
binary build (`psycopg[binary]` 3.3.4 or later), `psycopg-pool` 3.3.1 or later, and
[msgspec](https://jcristharif.com/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](../data/vectors.md), 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](../reference/compatibility.md) 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.

```console
$ 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`](../data/dataframes.md), `load_vertex_frame`, `load_edge_frame` |
| `pandas` | `pandas` 2.2 or later | [`to_pandas`](../data/dataframes.md), together with `arrow` |
| `polars` | `polars` 1.0 or later | [`to_polars`](../data/dataframes.md), together with `arrow` |
| `otel` | `opentelemetry-api` 1.33 or later | [`enable_tracing`](../production/observability.md) |

`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

```console
$ 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:

```python
import agensgraph

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

```text
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](https://github.com/skaiworldwide-oss/agensgraph-python). 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.

```console
$ 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.