{"id":874,"library":"gremlinpython","title":"Gremlin-Python","description":"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.","status":"active","version":"3.8.0","language":"python","source_language":"en","source_url":"https://github.com/apache/tinkerpop/tree/master/gremlin-python","tags":["graph database","apache tinkerpop","gremlin","graph traversal","database client"],"install":[{"cmd":"pip install gremlinpython","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"DriverRemoteConnection","correct":"from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection"},{"note":"While 'GraphTraversal' exists, `traversal()` for creating a GraphTraversalSource is typically imported from `anonymous_traversal`.","wrong":"from gremlin_python.process.graph_traversal import traversal","symbol":"traversal","correct":"from gremlin_python.process.anonymous_traversal import traversal"},{"note":"Used for anonymous traversals within other steps (e.g., `g.V().has('age', __.gt(20))`).","symbol":"__","correct":"from gremlin_python.process.graph_traversal import __"},{"note":"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()`.","wrong":"g.V().out().toList() (without statics.load_statics)","symbol":"statics.load_statics(globals())","correct":"from gremlin_python import statics\nstatics.load_statics(globals())"}],"quickstart":{"code":"import os\nfrom gremlin_python.driver.driver_remote_connection import DriverRemoteConnection\nfrom gremlin_python.process.anonymous_traversal import traversal\n\nGREMLIN_SERVER_URL = os.environ.get('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin')\n\n# Establish a remote connection to the Gremlin Server\nconnection = None\ntry:\n    connection = DriverRemoteConnection(GREMLIN_SERVER_URL, 'g')\n    g = traversal().withRemote(connection)\n\n    # Example Traversal: Get the count of all vertices\n    vertex_count = g.V().count().next()\n    print(f\"Number of vertices: {vertex_count}\")\n\n    # Add a vertex and then query it\n    new_vertex = g.addV('person').property('name', 'Alice').next()\n    print(f\"Added vertex: {new_vertex.id} - {new_vertex.label}\")\n\n    alice_name = g.V(new_vertex.id).values('name').next()\n    print(f\"Name of added vertex: {alice_name}\")\n\nfinally:\n    # Ensure the connection is closed to release resources\n    if connection:\n        connection.close()","lang":"python","description":"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."},"warnings":[{"fix":"Call `connection.close()` on your `DriverRemoteConnection` instance when you are finished with it.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Append an underscore (`_`) to any Gremlin step that clashes with a Python reserved keyword (e.g., `in_()`, `not_()`).","message":"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_()`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure every traversal chain ends with a terminal step like `.next()`, `.toList()`, `.toSet()`, or `.iterate()` to trigger execution.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rewrite queries using `has(key, P)` predicates or other suitable filtering steps to explicitly check property values.","message":"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.","severity":"breaking","affected_versions":"3.8.0+"},{"fix":"Review existing `repeat()` traversals and adjust logic if they relied on the previous hybrid local/global behavior. Test thoroughly.","message":"The semantics of the `repeat()` step changed to consistently treat its child traversal with global semantics, affecting how traversers are handled across loop iterations.","severity":"breaking","affected_versions":"3.8.0+"},{"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]`).","message":"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.","severity":"breaking","affected_versions":"3.8.0+"},{"fix":"Upgrade Python environment to 3.10 or later. If server-side lambdas are necessary, rewrite them in Gremlin-Groovy.","message":"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.","severity":"breaking","affected_versions":"3.8.0+"}],"env_vars":null,"last_verified":"2026-05-12T20:40:33.966Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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`.","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'.","error":"ModuleNotFoundError: No module named 'gremlin_python.process.anonymous_traversal'"},{"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.","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.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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.","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.","error":"websocket._exceptions.WebSocketConnectionClosedException: Connection is already closed."},{"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')`.","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`.","error":"SyntaxError: invalid syntax (when using Gremlin steps like .not() or .in())"},{"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()`.","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.","error":"Traversal returns an empty list or no visible output (e.g., `g.V()` does not produce results)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.8.1","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"3.7.6","pypi_latest":"3.8.1","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.19,"mem_mb":5.5,"disk_size":"29.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":5.5,"disk_size":"29.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.1,"import_time_s":0.14,"mem_mb":5.5,"disk_size":"32M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.5,"disk_size":"32M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.33,"mem_mb":6,"disk_size":"33.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.38,"mem_mb":6,"disk_size":"33.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.2,"import_time_s":0.29,"mem_mb":6,"disk_size":"35M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":6,"disk_size":"36M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.24,"mem_mb":6,"disk_size":"24.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":6,"disk_size":"25.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.3,"import_time_s":0.27,"mem_mb":6,"disk_size":"27M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":6,"disk_size":"28M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.25,"mem_mb":6.9,"disk_size":"24.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":6.5,"disk_size":"24.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.4,"import_time_s":0.27,"mem_mb":6.9,"disk_size":"27M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":6.5,"disk_size":"27M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":5.3,"disk_size":"29.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":5.3,"disk_size":"29.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6,"import_time_s":0.16,"mem_mb":5.3,"disk_size":"32M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gremlinpython","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":5.3,"disk_size":"32M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}