# How to Use the HugeGraph Python Client to Interact with HugeGraph: A Complete Developer Guide

> Master the HugeGraph Python client to efficiently manage schema, execute graph mutations, and run Gremlin queries. This guide simplifies your HugeGraph interaction.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: how-to-guide
- Published: 2026-02-24

---

**The HugeGraph Python client (`pyhugegraph`) wraps HugeGraph's HTTP API into convenient Python objects, using a lazy-initialization manager pattern to handle schema definition, graph mutations, and Gremlin queries with minimal overhead.**

The HugeGraph Python client, maintained in the `apache/incubator-hugegraph-ai` repository, transforms HugeGraph's REST endpoints into an idiomatic Python interface. This thin wrapper eliminates the need to manually construct HTTP requests while providing automatic authentication, version detection, and graphspace support for HugeGraph 3.0+. Whether you are defining property schemas or executing complex traversals, the client abstracts the underlying REST complexity into type-safe method calls.

## Architecture and Core Components

The client follows a **lazy-initialization manager** pattern that delays HTTP session creation until you actually request a specific operation. Understanding these four core components helps you navigate the source code effectively:

- **`PyHugeClient`** – The central entry point in [`hugegraph-python-client/src/pyhugegraph/client.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/client.py) that stores connection configuration and creates manager objects on demand using the `@manager_builder` decorator (lines 37‑45).

- **`HGraphConfig`** – Located in [`hugegraph-python-client/src/pyhugegraph/utils/huge_config.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/utils/huge_config.py), this class holds the server URL, credentials, target graph, and optional graphspace. Its `__post_init__` method (lines 44‑62) automatically queries `/versions` to detect server capabilities and enables graphspace support for HugeGraph 3.0+.

- **`HGraphSession`** – A thin wrapper around `requests.Session` found in [`hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py) that automatically injects authentication headers and timeout settings for every request.

- **Manager Classes** – Specialized wrappers for REST endpoints including `SchemaManager` ([`schema.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/schema.py)), `GraphManager` ([`graph.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/graph.py)), `GremlinManager` ([`gremlin.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/gremlin.py)), `GraphsManager` ([`graphs.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/graphs.py)), and `TaskManager`.

## Installation and Setup

Install the client from PyPI before connecting to your HugeGraph server:

```bash
pip install pyhugegraph

```

Verify your HugeGraph server is running and accessible at a known URL (default: `http://127.0.0.1:8080`). You will need valid credentials and the name of an existing graph to connect.

## Connecting to HugeGraph

Instantiate `PyHugeClient` with your server details. The constructor builds an `HGraphConfig` object and automatically detects your server version to determine available features.

```python
from pyhugegraph.client import PyHugeClient

client = PyHugeClient(
    url="http://127.0.0.1:8080",
    user="admin",
    pwd="admin",
    graph="hugegraph",
    graphspace=None,  # Optional; defaults to "DEFAULT" for v3+

)

print(client)  # Displays resolved configuration including detected version

```

As implemented in [`client.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/client.py) (lines 49‑60), the client resolves the graphspace parameter in `HGraphConfig.__post_init__` based on the server version response.

## Schema Management

Use the `SchemaManager` to define property keys, vertex labels, and edge labels before inserting data. The manager constructs REST payloads and sends them to the `/schema` endpoint.

```python
schema = client.schema()

# Define property keys

schema.propertyKey("name").asText().ifNotExist().create()
schema.propertyKey("birthDate").asText().ifNotExist().create()

# Create vertex labels with primary keys

schema.vertexLabel("Person") \
      .properties("name", "birthDate") \
      .usePrimaryKeyId() \
      .primaryKeys("name") \
      .ifNotExist() \
      .create()

schema.vertexLabel("Movie") \
      .properties("name") \
      .usePrimaryKeyId() \
      .primaryKeys("name") \
      .ifNotExist() \
      .create()

# Define relationships between vertex types

schema.edgeLabel("ActedIn") \
      .sourceLabel("Person") \
      .targetLabel("Movie") \
      .ifNotExist() \
      .create()

```

Each chained method builds a request payload that `SchemaManager` (defined in [`hugegraph-python-client/src/pyhugegraph/api/schema.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/api/schema.py)) validates before transmission.

## Graph Data Operations

The `GraphManager` provides CRUD operations for vertices and edges through the `graph()` accessor.

```python
graph = client.graph()

# Add vertices

p1 = graph.addVertex("Person", {"name": "Al Pacino", "birthDate": "1940-04-25"})
p2 = graph.addVertex("Person", {"name": "Robert De Niro", "birthDate": "1943-08-17"})
m1 = graph.addVertex("Movie", {"name": "The Godfather"})
m2 = graph.addVertex("Movie", {"name": "The Godfather Part II"})

# Create edges between vertices

graph.addEdge("ActedIn", p1.id, m1.id, {})
graph.addEdge("ActedIn", p1.id, m2.id, {})
graph.addEdge("ActedIn", p2.id, m2.id, {})

# Release resources

graph.close()

```

Under the hood, `GraphManager.addVertex` issues `POST` requests to `/graphs/{graph}/vertices` and `addEdge` posts to `/graphs/{graph}/edges`, as implemented in [`hugegraph-python-client/src/pyhugegraph/api/graph.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/api/graph.py).

## Querying with Gremlin

Execute Gremlin traversals through the `GremlinManager` to retrieve data without writing raw HTTP requests.

```python
gremlin = client.gremlin()

# Find all movies acted by Al Pacino

result = gremlin.gremlin(
    "g.V().hasLabel('Person').has('name', 'Al Pacino').out('ActedIn').valueMap()"
)

print(result)  # Returns a list of property maps for matched movies

```

The `gremlin()` method in [`hugegraph-python-client/src/pyhugegraph/api/gremlin.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/api/gremlin.py) sends the query string to the `/gremlin` endpoint and parses the JSON response into Python dictionaries.

## Administrative Operations

Manage multiple graphs and inspect server health using specialized managers.

### Working with Multiple Graphs

```python
graphs = client.graphs()

# Create a new graph with metadata

graphs.createGraph("my_graph", {"description": "Demo graph"})

# Remove a graph

graphs.dropGraph("my_graph")

```

The `GraphsManager` class in [`hugegraph-python-client/src/pyhugegraph/api/graphs.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/api/graphs.py) wraps the administrative `/graphs` APIs for creating and dropping graph instances.

### Checking Server Version

```python
version = client.version()
print("HugeGraph version:", version.get_version())

```

This queries the `/versions` endpoint via `VersionManager` in [`hugegraph-python-client/src/pyhugegraph/api/version.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/api/version.py) to confirm server compatibility.

## Summary

- The **HugeGraph Python client** uses a lazy-initialization pattern where managers like `SchemaManager` and `GraphManager` are instantiated only when accessed via `client.schema()` or `client.graph()`.
- **Configuration handling** in `HGraphConfig` automatically detects HugeGraph server versions and enables graphspace support for versions 3.0 and above.
- **Schema definition** follows a fluent API pattern where chained method calls build REST payloads for property keys, vertex labels, and edge labels.
- **Data manipulation** methods such as `addVertex()` and `addEdge()` in `GraphManager` abstract the HTTP POST requests to the vertices and edges endpoints.
- **Gremlin queries** execute through `GremlinManager.gremlin()`, returning parsed JSON results without manual HTTP handling.

## Frequently Asked Questions

### How do I install and configure the HugeGraph Python client?

Install the package using `pip install pyhugegraph`. To configure the client, instantiate `PyHugeClient` with your server URL, credentials, graph name, and optional graphspace. The client automatically detects your HugeGraph version via the `/versions` endpoint and adjusts capabilities accordingly, as implemented in `HGraphConfig.__post_init__`.

### What is the difference between `graph` and `graphspace` in the client configuration?

The `graph` parameter specifies the target graph database name, while `graphspace` (defaulting to `"DEFAULT"` for HugeGraph 3.0+) provides a namespace for multi-tenant deployments. According to the source code in [`hugegraph-python-client/src/pyhugegraph/utils/huge_config.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/utils/huge_config.py), the client automatically sets the graphspace based on version detection if not explicitly provided.

### How does the client handle authentication and session management?

The `HGraphSession` class in [`hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py) wraps `requests.Session` and automatically injects authentication headers and timeout settings into every HTTP request. When you create a `PyHugeClient`, it initializes this session wrapper with your provided credentials, ensuring all subsequent API calls include proper authentication without manual header manipulation.

### Can I use the HugeGraph Python client with server versions older than 3.0?

Yes, the client maintains backward compatibility. The `HGraphConfig` class detects the server version during initialization and disables graphspace features for older servers. However, you should verify that specific manager methods you intend to use exist in your server's REST API version, as newer endpoints may not be available on legacy deployments.