GQL

This is a GraphQL client for Python. Plays nicely with graphene, graphql-core, graphql-js and any other GraphQL implementation compatible with the GraphQL specification.

GQL architecture is inspired by React-Relay and Apollo-Client.

Documentation

The complete documentation for GQL can be found at gql.readthedocs.io.

Features

Execute GraphQL queries using different protocols:
- http
- websockets:
  - apollo or graphql-ws protocol
  - Phoenix channels
  - AWS AppSync realtime protocol (experimental)
Possibility to validate the queries locally using a GraphQL schema provided locally or fetched from the backend using an instrospection query
Supports GraphQL queries, mutations and subscriptions
Supports sync or async usage, allowing concurrent requests
Supports File uploads
Supports Custom scalars / Enums
Supports Batching requests
gql-cli script to execute GraphQL queries or download schemas from the command line
DSL module to compose GraphQL queries dynamically

Installation

You can install GQL with all the optional dependencies using pip:

# Quotes may be required on certain shells such as zsh.
pip install "gql[all]"

NOTE: See also the documentation to install GQL with less extra dependencies depending on the transports you would like to use or for alternative installation methods.

Usage

Sync usage

from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

# Select your transport with a defined url endpoint
transport = AIOHTTPTransport(url="https://countries.trevorblades.com/")

# Create a GraphQL client using the defined transport
client = Client(transport=transport)

# Provide a GraphQL query
query = gql(
    """
    query getContinents {
      continents {
        code
        name
      }
    }
"""
)

# Execute the query on the transport
result = client.execute(query)
print(result)

Executing the above code should output the following result:

$ python basic_example.py
{'continents': [{'code': 'AF', 'name': 'Africa'}, {'code': 'AN', 'name': 'Antarctica'}, {'code': 'AS', 'name': 'Asia'}, {'code': 'EU', 'name': 'Europe'}, {'code': 'NA', 'name': 'North America'}, {'code': 'OC', 'name': 'Oceania'}, {'code': 'SA', 'name': 'South America'}]}

WARNING: Please note that this basic example won't work if you have an asyncio event loop running. In some python environments (as with Jupyter which uses IPython) an asyncio event loop is created for you. In that case you should use instead the async usage example.

Async usage

import asyncio

from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport


async def main():

    # Select your transport with a defined url endpoint
    transport = AIOHTTPTransport(url="https://countries.trevorblades.com/graphql")

    # Create a GraphQL client using the defined transport
    client = Client(transport=transport)

    # Provide a GraphQL query
    query = gql(
        """
        query getContinents {
          continents {
            code
            name
          }
        }
    """
    )

    # Using `async with` on the client will start a connection on the transport
    # and provide a `session` variable to execute queries on this connection
    async with client as session:

        # Execute the query
        result = await session.execute(query)
        print(result)


asyncio.run(main())

Contributing

See CONTRIBUTING.md

License

MIT License

Release files for gql 4.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gql 4.0.0
File	Size	Uploaded
gql-4.0.0.tar.gz	215.6 kB	Aug 17, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for gql 4.0.0
File	Interpreter	ABI	Platform	Reset
gql-4.0.0-py3-none-any.whl 89.9 kB Aug 17, 2025	Python 3	none	any	Details

Total release size: 305.5 kB

Release files / gql-4.0.0.tar.gz

Download URL	gql-4.0.0.tar.gz
Size	215.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`f22980844eb6a7c0266ffc70f111b9c7e7c7c13da38c3b439afc7eab3d7c9c8e`
BLAKE2b-256 checksum How to use checksums	`069fcf224a88ed71eb223b7aa0b9ff0aa10d7ecc9a4acdca2279eb046c26d5dc`
Upload date	Aug 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Release files / gql-4.0.0-py3-none-any.whl

Download URL	gql-4.0.0-py3-none-any.whl
Size	89.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f3beed7c531218eb24d97cb7df031b4a84fdb462f4a2beb86e2633d395937479`
BLAKE2b-256 checksum How to use checksums	`ac9430bbd09e8d45339fa77a48f5778d74d47e9242c11b3cd1093b3d994770a5`
Upload date	Aug 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`