{"id":989,"library":"gql","title":"gql: GraphQL Client for Python","description":"gql is a powerful and flexible GraphQL client library for Python, designed to simplify interacting with GraphQL APIs. It supports both synchronous and asynchronous operations, offering various transports like HTTP (via aiohttp, httpx, requests) and WebSockets. The library plays well with `graphql-core` and other GraphQL implementations, enabling features like local schema validation and dynamic query composition using a DSL module. The current stable version is 4.0.0, with active development including beta releases (e.g., v4.3.0b0) leading to future minor or major updates.","status":"active","version":"4.0.0","language":"python","source_language":"en","source_url":"https://github.com/graphql-python/gql","tags":["graphql","client","async","http","websockets","dsl","api-client"],"install":[{"cmd":"pip install \"gql[all]\"","lang":"bash","label":"Recommended with all optional dependencies"},{"cmd":"pip install gql","lang":"bash","label":"Minimal install"}],"dependencies":[{"reason":"Core GraphQL parsing and execution logic.","package":"graphql-core","optional":false},{"reason":"Common asynchronous HTTP transport (included with `gql[aiohttp]` or `gql[all]`).","package":"aiohttp","optional":true}],"imports":[{"symbol":"Client","correct":"from gql import Client"},{"symbol":"gql","correct":"from gql import gql"},{"symbol":"AIOHTTPTransport","correct":"from gql.transport.aiohttp import AIOHTTPTransport"},{"note":"Used for GraphQL subscriptions over WebSockets.","symbol":"WSAsyncTransport","correct":"from gql.transport.websockets import WSAsyncTransport"},{"note":"As of v4.0.0, 'gql' and 'dsl_gql' functions return a 'GraphQLRequest' object, not a 'DocumentNode'. 'execute' methods also expect 'GraphQLRequest'.","wrong":"from graphql import DocumentNode","symbol":"GraphQLRequest","correct":"from gql.graphql_request import GraphQLRequest"},{"symbol":"dsl_gql","correct":"from gql.dsl import dsl_gql"},{"symbol":"DSLQuery","correct":"from gql.dsl import DSLQuery"},{"symbol":"DSLSchema","correct":"from gql.dsl import DSLSchema"}],"quickstart":{"code":"import asyncio\nimport os\nfrom gql import Client, gql\nfrom gql.transport.aiohttp import AIOHTTPTransport\n\nasync def main():\n    # Replace with your GraphQL endpoint\n    # For a real application, consider using environment variables for the URL and auth.\n    graphql_url = os.environ.get('GRAPHQL_ENDPOINT_URL', 'https://countries.trevorblades.com/graphql')\n    auth_token = os.environ.get('GRAPHQL_AUTH_TOKEN', '')\n\n    headers = {}\n    if auth_token:\n        headers['Authorization'] = f'Bearer {auth_token}'\n\n    # Select your transport\n    transport = AIOHTTPTransport(url=graphql_url, headers=headers)\n\n    # Create a GraphQL client\n    client = Client(transport=transport, fetch_schema_from_transport=True)\n\n    # Provide a GraphQL query (now returns GraphQLRequest object in v4+)\n    query = gql(\n        \"\"\"\n        query getContinents {\n            continents {\n                code\n                name\n            }\n        }\n        \"\"\"\n    )\n\n    # Using `async with` on the client will start a connection\n    # and provide a `session` variable to execute queries on this connection.\n    async with client as session:\n        # Execute the query (now accepts GraphQLRequest object in v4+)\n        result = await session.execute(query)\n        print(result)\n\nif __name__ == \"__main__\":\n    # If an asyncio event loop is already running, use this instead:\n    # import nest_asyncio\n    # nest_asyncio.apply()\n    # asyncio.run(main())\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Update 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.","message":"As 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If 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.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update any exception handling blocks to catch `TransportConnectionClosed` instead of `ConnectionClosed`. Import the new exception from `gql.transport.exceptions`.","message":"The `ConnectionClosed` exception has been replaced by `TransportConnectionClosed` for connection-related errors.","severity":"breaking","affected_versions":">=4.0.0a0"},{"fix":"In 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions with async transports"}],"env_vars":null,"last_verified":"2026-05-12T22:17:34.282Z","next_check":"2026-06-27T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.0.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":9.4,"disk_size":"67.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":9.4,"disk_size":"67.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":9.4,"disk_size":"24.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":9.4,"disk_size":"24.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7.9,"import_time_s":0.21,"mem_mb":9.4,"disk_size":"69M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":9.4,"disk_size":"70M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.3,"import_time_s":0.21,"mem_mb":9.4,"disk_size":"25M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":9.4,"disk_size":"26M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.49,"mem_mb":10.7,"disk_size":"72.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":10.7,"disk_size":"72.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":10.7,"disk_size":"26.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.51,"mem_mb":10.7,"disk_size":"27.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.8,"import_time_s":0.42,"mem_mb":10.7,"disk_size":"74M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":10.7,"disk_size":"75M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":0.41,"mem_mb":10.7,"disk_size":"28M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.38,"mem_mb":10.7,"disk_size":"28M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.66,"mem_mb":10.7,"disk_size":"63.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":10.7,"disk_size":"63.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":10.7,"disk_size":"18.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":10.7,"disk_size":"19.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.4,"import_time_s":0.57,"mem_mb":10.7,"disk_size":"66M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":10.7,"disk_size":"66M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.5,"import_time_s":0.58,"mem_mb":10.7,"disk_size":"19M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":10.7,"disk_size":"20M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.66,"mem_mb":10.8,"disk_size":"62.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":10.8,"disk_size":"62.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":10.8,"disk_size":"18.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":10.8,"disk_size":"18.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.5,"import_time_s":0.58,"mem_mb":10.8,"disk_size":"65M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":10.8,"disk_size":"65M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.5,"import_time_s":0.54,"mem_mb":10.8,"disk_size":"19M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":10.8,"disk_size":"19M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":9.5,"disk_size":"67.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":9.5,"disk_size":"67.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":9.5,"disk_size":"24.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":9.5,"disk_size":"24.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":9.2,"import_time_s":0.27,"mem_mb":9.5,"disk_size":"70M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":9.5,"disk_size":"70M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.9,"import_time_s":0.31,"mem_mb":9.5,"disk_size":"26M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":9.5,"disk_size":"26M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}