GraphQL client for Python
Project Links
Meta
Author: Syrus Akbary
Requires Python: >=3.8.1
Classifiers
Development Status
- 5 - Production/Stable
Intended Audience
- Developers
Topic
- Software Development :: Libraries
Programming Language
- Python :: 3
- Python :: 3 :: Only
- Python :: 3.9
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
- Python :: Implementation :: PyPy
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
4.4.0b0
Jul 21, 2026
4.3.0b3
May 30, 2026
4.3.0b2
Apr 02, 2026
4.3.0b1
Mar 30, 2026
4.3.0b0
Jan 09, 2026
4.2.0b0
Sep 05, 2025
4.1.0b0
Aug 17, 2025
4.0.0
Aug 17, 2025
4.0.0b0
May 28, 2025
4.0.0a0
May 20, 2025
3.6.0b4
Feb 18, 2025
3.6.0b3
Jan 20, 2025
3.6.0b2
Apr 14, 2024
3.6.0b1
Feb 08, 2024
3.6.0b0
Jan 03, 2024
3.5.3
May 20, 2025
3.5.2
Mar 06, 2025
3.5.1
Feb 19, 2025
3.5.0
Jan 03, 2024
3.5.0b9
Dec 15, 2023
3.5.0b8
Nov 19, 2023
3.5.0b7
Nov 14, 2023
3.5.0b6
Oct 04, 2023
3.5.0b5
Jul 26, 2023
3.5.0b4
May 06, 2023
3.5.0b3
Feb 23, 2023
3.5.0b2
Feb 23, 2023
3.5.0b1
Feb 22, 2023
3.5.0b0
Nov 26, 2022
3.5.0a0
Nov 07, 2022
3.4.1
May 06, 2023
3.4.0
Jul 14, 2022
3.3.0
May 20, 2022
3.2.0
Apr 12, 2022
3.1.0
Mar 11, 2022
3.0.0
Jan 22, 2022
3.0.0rc1
Jan 16, 2022
3.0.0rc0
Dec 10, 2021
3.0.0b1
Nov 22, 2021
3.0.0b0
Oct 26, 2021
3.0.0a6
Jun 09, 2021
3.0.0a5
Nov 21, 2020
3.0.0a4
Nov 01, 2020
3.0.0a3
Oct 15, 2020
3.0.0a2
Oct 04, 2020
3.0.0a1
Jul 13, 2020
3.0.0a0
May 17, 2020
2.0.0
May 17, 2020
0.5.0
May 10, 2020
0.4.0
Mar 11, 2020
0.3.0
Jan 24, 2020
0.2.0
Dec 29, 2019
0.1.0
Aug 06, 2016
Wheel compatibility matrix
Files in release
Extras:
Dependencies:
graphql-core
(<3.3,>=3.2)
yarl
(<2.0,>=1.6)
backoff
(<3.0,>=1.11.1)
anyio
(<5,>=3.0)