Install & Compatibility
Where this runs
tested against v4.0.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.480s · 68MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.2s · import 0.436s · 70MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from gql import Client
AIOHTTPTransport
✓ from gql.transport.aiohttp import AIOHTTPTransport
WSAsyncTransport
✓ from gql.transport.websockets import WSAsyncTransport
Used for GraphQL subscriptions over WebSockets.
GraphQLRequest
✓ from gql.graphql_request import GraphQLRequest
✗ from graphql import DocumentNode
As of v4.0.0, 'gql' and 'dsl_gql' functions return a 'GraphQLRequest' object, not a 'DocumentNode'. 'execute' methods also expect 'GraphQLRequest'.
dsl_gql
✓ from gql.dsl import dsl_gql
DSLQuery
✓ from gql.dsl import DSLQuery
DSLSchema
✓ from gql.dsl import DSLSchema
This quickstart demonstrates how to set up an asynchronous `gql` client using `AIOHTTPTransport`, define a GraphQL query, and execute it. It includes handling potential authentication headers and uses the recommended `async with client as session:` pattern for managing connections. Ensure you have `aiohttp` installed (e.g., `pip install "gql[aiohttp]"` or `pip install "gql[all]"`) for this example to run.
import asyncio
import os
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport
async def main():
# Replace with your GraphQL endpoint
# For a real application, consider using environment variables for the URL and auth.
graphql_url = os.environ.get('GRAPHQL_ENDPOINT_URL', 'https://countries.trevorblades.com/graphql')
auth_token = os.environ.get('GRAPHQL_AUTH_TOKEN', '')
headers = {}
if auth_token:
headers['Authorization'] = f'Bearer {auth_token}'
# Select your transport
transport = AIOHTTPTransport(url=graphql_url, headers=headers)
# Create a GraphQL client
client = Client(transport=transport, fetch_schema_from_transport=True)
# Provide a GraphQL query (now returns GraphQLRequest object in v4+)
query = gql(
"""
query getContinents {
continents {
code
name
}
}
"""
)
# Using `async with` on the client will start a connection
# and provide a `session` variable to execute queries on this connection.
async with client as session:
# Execute the query (now accepts GraphQLRequest object in v4+)
result = await session.execute(query)
print(result)
if __name__ == "__main__":
# If an asyncio event loop is already running, use this instead:
# import nest_asyncio
# nest_asyncio.apply()
# asyncio.run(main())
asyncio.run(main())
Debug
Known issues
breakingAs of v4.0.0, the `gql()` and `dsl_gql()` functions now return a `GraphQLRequest` object instead of a `DocumentNode`. All `client.execute()` and `client.subscribe()` methods also now accept a `GraphQLRequest` object as their primary argument.fixUpdate calls to `gql()` and `dsl_gql()` to expect `GraphQLRequest` objects. Pass `GraphQLRequest` objects directly to `execute()` and `subscribe()` methods. The `GraphQLRequest` object encapsulates the document, variable values, and operation name.
affects: >=4.0.0
breakingThe `AIOHTTPTransport`'s `ssl` parameter now defaults to `True` (enabling SSL certificate verification) starting from v4.0.0 (introduced in v4.0.0a0). Previously, it defaulted to `False` which could lead to security vulnerabilities by accepting self-signed certificates without warning.fixIf your GraphQL endpoint uses a self-signed or otherwise untrusted SSL certificate and you need to bypass verification (not recommended for production), explicitly set `ssl=False` in the `AIOHTTPTransport` constructor. Otherwise, ensure your certificates are properly configured and trusted.
affects: >=4.0.0
breakingThe `ConnectionClosed` exception has been replaced by `TransportConnectionClosed` for connection-related errors.fixUpdate any exception handling blocks to catch `TransportConnectionClosed` instead of `ConnectionClosed`. Import the new exception from `gql.transport.exceptions`.
affects: >=4.0.0a0
gotchaWhen using synchronous `client.execute()` or `client.subscribe()` methods from an asynchronous transport (like `AIOHTTPTransport`) in environments where an asyncio event loop is already running (e.g., Jupyter notebooks, IPython), it might cause issues or block. `gql` will try to run an event loop itself, which conflicts with an already running one.fixIn such environments, explicitly use the asynchronous `await session.execute(query)` pattern within an `async def` function. If you must use synchronous client methods, consider using libraries like `nest_asyncio` to patch the event loop for compatibility.
affects: All versions with async transports
Upgrade
Version history
4.0.0latest on PyPI · released Aug 17, 2025
Audit
Dependencies
graphql-corerequiredCore GraphQL parsing and execution logic.
aiohttpoptionalCommon asynchronous HTTP transport (included with `gql[aiohttp]` or `gql[all]`).