gremlinpython

library3.8.1pypypi✓ verified 24d ago

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.

database aws http-networking serialization data

pip install gremlinpython

package ↗homepage ↗

INSTALL

IMPORT

SIG · GREMLINPYTHON

gremlinpython

databasepythonv3.8.1

Install

4.3s avg

Import

227ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.238s · 29.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.3s · import 0.216s · 32MB

29MB installed

● package 29MB

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()

Debug

Known issues

gotchaAlways 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.

affects: All versions

gotchaSome 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_()`).

affects: All versions

gotchaGremlin-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.

affects: All versions

breakingThe `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.

affects: 3.8.0+

breakingThe 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.

affects: 3.8.0+

breakingThe `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]`).

affects: 3.8.0+

breakingApache 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.

affects: 3.8.0+

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'.

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

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.

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.

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.

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.

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

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')`.

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.

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()`.

Upgrade

Version history

3.8.1latest on PyPI · released Apr 7, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

Anthropic

Resources

packagehttps://pypi.org/project/gremlinpython/ ↗

homepagehttps://tinkerpop.apache.org ↗