Gremlin-Python

3.8.0 verified Tue May 12 auth: no python install: verified

Gremlin-Python is the Python Language Variant (GLV) for Apache TinkerPop, a graph computing framework. It enables users to express complex graph traversals using Python syntax, connecting to any TinkerPop-enabled graph system (like Gremlin Server or Amazon Neptune). The library is actively maintained and releases are typically aligned with major Apache TinkerPop versions, with the current version being 3.8.0.

pip install gremlinpython

Common errors

error ModuleNotFoundError: No module named 'gremlin_python.process.anonymous_traversal' ↓

cause This error typically occurs when the 'gremlinpython' library is not installed, or there's an issue with the Python environment's path, or an incorrect import path for specific submodules like 'anonymous_traversal'.

fix

Ensure gremlinpython is installed using pip install gremlinpython and that the import statements accurately reflect the library's structure, for example: from gremlin_python.process.anonymous_traversal import traversal and from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection.

error ConnectionRefusedError: [Errno 111] Connection refused ↓

cause This error indicates that the Python client could not establish a connection to the Gremlin Server, usually because the server is not running, is inaccessible at the specified host and port, or a firewall is blocking the connection.

fix

Verify that the Gremlin Server is running and listening on the correct host and port (default is ws://localhost:8182/gremlin). Check network connectivity and any firewall rules that might be blocking the connection.

error websocket._exceptions.WebSocketConnectionClosedException: Connection is already closed. ↓

cause This exception arises when the Gremlin Server closes the WebSocket connection, often due to an idle timeout, network instability, or explicit server-side closure, while the client attempts to use it.

fix

Implement robust connection handling, including retry mechanisms with exponential backoff and logic to re-establish the connection upon closure. For long-running applications, ensure the connection is actively used or periodically 'pinged' to prevent idle timeouts.

error SyntaxError: invalid syntax (when using Gremlin steps like .not() or .in()) ↓

cause Several Gremlin step names (e.g., `not`, `in`, `as`, `and`, `or`, `from`, `is`, `list`, `set`, `all`, `global`) are Python reserved keywords, leading to `SyntaxError` when used directly without modification in `gremlinpython`.

fix

Append an underscore (_) to any Gremlin step name that conflicts with a Python reserved keyword. For example, use g.V().not_(__.inE()), g.V().in_('knows'), or g.V().as_('x').

error Traversal returns an empty list or no visible output (e.g., `g.V()` does not produce results) ↓

cause In `gremlinpython`, traversals are lazily evaluated and are not submitted to the Gremlin Server for execution until a terminal step is explicitly called. Without a terminal step, the traversal object is merely built, not run.

fix

Always append a terminal step to your traversal to execute it and retrieve results. Common terminal steps include .next(), .toList(), .toSet(), or .iterate(). For example, results = g.V().has('name', 'marko').toList().

Warnings

gotcha Always close the `DriverRemoteConnection`. Failing to do so can lead to 'Unclosed Client Session' errors and resource leaks, especially in long-running applications or when repeatedly creating connections. Use a `try...finally` block or a context manager if available (though a direct `close()` call is most common for `DriverRemoteConnection`). ↓

fix Call `connection.close()` on your `DriverRemoteConnection` instance when you are finished with it.

gotcha Some Gremlin step names are Python reserved keywords (e.g., `in`, `and`, `as`, `from`, `is`, `not`, `or`, `set`). These steps must be suffixed with an underscore (`_`) in Gremlin-Python (e.g., `g.V().in_()`, `__.not_()`). ↓

fix Append an underscore (`_`) to any Gremlin step that clashes with a Python reserved keyword (e.g., `in_()`, `not_()`).

gotcha Gremlin-Python traversals are lazy; they do not execute until a terminal step is called. Common terminal steps include `.next()`, `.toList()`, `.toSet()`, or `.iterate()`. Forgetting a terminal step means your traversal will not be sent to the server. ↓

fix Ensure every traversal chain ends with a terminal step like `.next()`, `.toList()`, `.toSet()`, or `.iterate()` to trigger execution.

breaking The `has(key, traversal)` step was removed due to its confusing behavior where it checked if the traversal yielded *any* results, not if the property's value matched the traversal's condition. This is a breaking change. ↓

fix Rewrite queries using `has(key, P)` predicates or other suitable filtering steps to explicitly check property values.

breaking The semantics of the `repeat()` step changed to consistently treat its child traversal with global semantics, affecting how traversers are handled across loop iterations. ↓

fix Review existing `repeat()` traversals and adjust logic if they relied on the previous hybrid local/global behavior. Test thoroughly.

breaking The `limit(local)`, `range(local)`, and `tail(local)` steps now consistently return a collection (e.g., a list) when operating on an iterable, even if the result size is one. Previously, a single result would be 'unboxed' and returned directly. ↓

fix Update application code to always expect a collection (e.g., `list`) from these steps and handle single-item results by accessing the first element if needed (e.g., `result[0]`).

breaking Apache TinkerPop 3.8.0 (and thus Gremlin-Python 3.8.0) requires Python 3.10 or newer. Support for earlier Python versions has been dropped. Additionally, Jython support was entirely removed, meaning native Python lambdas no longer execute in Gremlin Server; use Gremlin-Groovy for server-side lambdas. ↓

fix Upgrade Python environment to 3.10 or later. If server-side lambdas are necessary, rewrite them in Gremlin-Groovy.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.19s 29.6M

3.10 alpine (musl) - - 0.19s 29.9M

3.10 slim (glibc) wheel 5.1s 0.14s 32M

3.10 slim (glibc) - - 0.13s 32M

3.11 alpine (musl) wheel - 0.33s 33.1M

3.11 alpine (musl) - - 0.38s 33.5M

3.11 slim (glibc) wheel 4.2s 0.29s 35M

3.11 slim (glibc) - - 0.27s 36M

3.12 alpine (musl) wheel - 0.24s 24.8M

3.12 alpine (musl) - - 0.28s 25.2M

3.12 slim (glibc) wheel 3.3s 0.27s 27M

3.12 slim (glibc) - - 0.26s 28M

3.13 alpine (musl) wheel - 0.25s 24.3M

3.13 alpine (musl) - - 0.26s 24.5M

3.13 slim (glibc) wheel 3.4s 0.27s 27M

3.13 slim (glibc) - - 0.26s 27M

3.9 alpine (musl) wheel - 0.17s 29.9M

3.9 alpine (musl) - - 0.19s 29.9M

3.9 slim (glibc) wheel 6.0s 0.16s 32M

3.9 slim (glibc) - - 0.16s 32M

Imports

DriverRemoteConnection

from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection

traversal
wrong
```
from gremlin_python.process.graph_traversal import traversal
```
correct
```
from gremlin_python.process.anonymous_traversal import traversal
```
While 'GraphTraversal' exists, `traversal()` for creating a GraphTraversalSource is typically imported from `anonymous_traversal`.
__
```
from gremlin_python.process.graph_traversal import __
```
Used for anonymous traversals within other steps (e.g., `g.V().has('age', __.gt(20))`).
statics.load_statics(globals())
wrong
```
g.V().out().toList() (without statics.load_statics)
```
correct
```
from gremlin_python import statics
statics.load_statics(globals())
```
Calling `statics.load_statics(globals())` allows direct use of many Gremlin steps (like `out()`, `in_()`) without the `__` prefix. Without it, you'd need `g.V().__.out().toList()`.

Quickstart last tested: 2026-04-24

Connects to a local Gremlin Server (defaults to `ws://localhost:8182/gremlin`), executes a simple traversal to count vertices, adds a new vertex, and then queries its name. It properly handles connection closing.

import os
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.process.anonymous_traversal import traversal

GREMLIN_SERVER_URL = os.environ.get('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin')

# Establish a remote connection to the Gremlin Server
connection = None
try:
    connection = DriverRemoteConnection(GREMLIN_SERVER_URL, 'g')
    g = traversal().withRemote(connection)

    # Example Traversal: Get the count of all vertices
    vertex_count = g.V().count().next()
    print(f"Number of vertices: {vertex_count}")

    # Add a vertex and then query it
    new_vertex = g.addV('person').property('name', 'Alice').next()
    print(f"Added vertex: {new_vertex.id} - {new_vertex.label}")

    alice_name = g.V(new_vertex.id).values('name').next()
    print(f"Name of added vertex: {alice_name}")

finally:
    # Ensure the connection is closed to release resources
    if connection:
        connection.close()