How to install GQLAlchemy

There are two main ways of installing GQLAlchemy: with package managers such as pip and uv, and by building it from source.

Prerequisites

To install GQLAlchemy, you will need the following:

Python 3.10+
pymgclient:
- Install pymgclient build prerequisites
- Install pymgclient via pip:
```
pip install --user pymgclient
```

Note

GQLAlchemy is tested on Python 3.10 through 3.14 in CI. Some optional extras (for example TensorFlow/TF-GNN stacks) are available only for a subset of Python versions due to upstream wheel availability.

Install with pip

After you’ve installed the prerequisites, run the following command to install GQLAlchemy:

pip install gqlalchemy

With the above command, you get the default GQLAlchemy installation which doesn’t include import/export support for certain formats (see below). To get additional import/export capabilities, use one of the following install options:

pip install gqlalchemy[arrow] # Support for the CSV, Parquet, ORC and IPC/Feather/Arrow formats
pip install gqlalchemy[dgl] # DGL support (also includes torch)
pip install gqlalchemy[dot] # DOT graph import support (pydot)
pip install gqlalchemy[docker] # Docker support

pip install gqlalchemy[all] # All of the above

If you intend to use GQLAlchemy with PyTorch Geometric support, that library must be installed manually:

pip install gqlalchemy[torch_pyg] # prerequisite
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.13.0+cpu.html"

Note

If you are using the zsh terminal, surround gqlalchemy[$extras] with quotes:

pip install 'gqlalchemy[arrow]'

Build from source

Clone or download the GQLAlchemy source code locally and run the following command to build it from source with uv:

uv sync --all-extras

The uv sync --all-extras command installs GQLAlchemy with all extras (optional dependencies). Alternatively, you can use the --extra option to define what extras to install:

uv sync # No extras

uv sync --extra arrow # Support for the CSV, Parquet, ORC and IPC/Feather/Arrow formats
uv sync --extra dgl # Installs torch (DGL must be installed separately, see below)
uv sync --extra dot # DOT graph import support (pydot)
uv sync --extra docker # Docker support

The dgl and torch_pyg extras install PyTorch only. DGL and PyTorch Geometric wheels must be installed separately due to their custom package indexes:

# DGL
uv sync --extra dgl
uv pip install dgl -f https://data.dgl.ai/wheels/torch-2.4/repo.html

# PyTorch Geometric
uv sync --extra torch_pyg
uv pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-2.4.0+cpu.html

To run the tests, make sure you have an active Memgraph instance, and execute one of the following commands:

uv run pytest . -k "not slow" # If all extras installed

uv run pytest . -k "not slow and not extras" # Otherwise

If you’ve installed only certain extras, it’s also possible to run their associated tests:

uv run pytest . -k "arrow"
uv run pytest . -k "dgl"
uv run pytest . -k "docker"