Python code generator that turns a GraphQL schema and your operations into a fully typed, async (or sync) Python client built on Pydantic. You write your queries, mutations and subscriptions in GraphQL, and ariadne-codegen generates a typed Python method for each one, returning Pydantic models - so you get autocompletion and static type checking instead of hand-writing query strings and parsing raw JSON.
📖 Documentation · Step-by-step example · Configuration reference
- Fully typed models - Pydantic models for schema types, inputs, enums, fragments, and every operation's result.
- Typed client methods - each query, mutation, and subscription becomes a method with typed arguments and a typed return value.
- Async or sync - generate an async client (default) or a synchronous one.
- Subscriptions - real-time updates over WebSockets (
graphql-transport-ws). - File uploads - multipart requests via the GraphQL multipart request spec.
- Custom scalars - map GraphQL scalars to your own Python types with
serialize/parsehooks. - Extensible output - inject mixins into generated models, copy in your own files, or swap the base client (custom auth, or to drop the
httpx/websocketsdeps). - Flexible schema sources - a local file, installed Python packages, or remote introspection.
- Plugin system - customize generation through hooks, plus ready-made plugins (shorter results, extracted operation strings, forward refs, …).
- More - programmatic query building, OpenTelemetry tracing, multiple clients per project, a schema-copy mode, and deprecation warnings for deprecated parts of your schema.
Requires Python 3.10 or newer.
pip install ariadne-codegen
Add subscription (WebSocket) support with:
pip install ariadne-codegen[subscriptions]
Generate a typed client from three files.
1. Describe your schema in schema.graphql:
type Query {
hello(name: String!): String!
}2. Write the operations you need in queries.graphql:
query Greet($name: String!) {
hello(name: $name)
}3. Point ariadne-codegen at them in pyproject.toml:
[tool.ariadne-codegen]
schema_path = "schema.graphql"
queries_path = "queries.graphql"Then generate the client:
ariadne-codegen
This creates a graphql_client package. Use it:
import asyncio
from graphql_client import Client
async def main():
async with Client(url="https://example.com/graphql") as client:
result = await client.greet(name="World")
print(result.hello)
asyncio.run(main())greet is a typed method generated from your Greet operation, and result is a
validated Pydantic model. See the step-by-step example
for a walk-through of everything that gets generated.
Contributions are welcome! See CONTRIBUTING.md for how to report bugs, work on issues, and open pull requests.
Also make sure you follow @AriadneGraphQL on Twitter for latest updates, news and random musings!