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.
Install & Compatibility
Where this runs
tested against v3.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.241s · 29.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 4.3s · import 0.218s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DriverRemoteConnection
✓ from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
traversal
✓ from gremlin_python.process.anonymous_traversal import traversal
✗ from gremlin_python.process.graph_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())
✓ from gremlin_python import statics
statics.load_statics(globals())
✗ g.V().out().toList() (without statics.load_statics)
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()`.
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()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gremlin_python.process.anonymous_traversal'
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'.
fixEnsure `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`.
ConnectionRefusedError: [Errno 111] Connection refused
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.
fixVerify 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.
websocket._exceptions.WebSocketConnectionClosedException: Connection is already closed.
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.
fixImplement 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.
SyntaxError: invalid syntax (when using Gremlin steps like .not() or .in())
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`.
fixAppend 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')`. Traversal returns an empty list or no visible output (e.g., `g.V()` does not produce results)
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.
fixAlways 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()`. Audit
Dependencies
No dependency data recorded yet.