graphene review
Graphene lets Python classes define a GraphQL schema. ObjectType, Field, Mutation, Enum, Interface, Union, and Relay helpers turn class declarations and resolver methods into a graphql-core schema that any GraphQL client can query. Version 3.4.3 fixes invalid UUID variables so they produce a proper GraphQL error instead of an AttributeError. The package stays data-source neutral; Django, SQLAlchemy, Mongo, and federation support live in separate integrations.
Graphene 3.4.3 installed in 0.2 seconds and occupied 3 MB across 6 packages in our sandbox, with 0 pip-audit findings and no py.typed marker. Install it for a Python class-first GraphQL schema; skip it when SDL ownership, strict library typing, or built-in protection from N+1 queries is non-negotiable.
We installed it
| Install | ✓ · 0.2s | 6 packages on disk · 3 MB |
| Import | ✓ | import graphene in 0.75s · pure Python |
| Known vulns | 0 | (pip-audit) |
Answers from our run
Does graphene install cleanly?
Yes. In a fresh container with an empty cache, pip install graphene finished in 0.2s, leaving 6 packages and 3 MB on disk. pip-audit reported no known vulnerabilities.
What does graphene need to run?
Python 3.x, and nothing compiled: it is pure Python. In our run import graphene succeeded in 0.75s.
graphene or strawberry-graphql: which should you use?
strawberry-graphql: Choose it for a type-annotation and dataclass-oriented GraphQL API with first-class async patterns. Graphene 3.4.3 installed in 0.2 seconds and occupied 3 MB across 6 packages in our sandbox, with 0 pip-audit findings and no py.typed marker.
When should you not use graphene?
You prefer schema-first GraphQL with SDL as the source of truth; Graphene's class metaprogramming makes Python declarations primary.
Use it if
- You want a code-first GraphQL schema expressed as Python classes and resolver methods.
- A Django or SQLAlchemy application can use a maintained Graphene integration around its existing models.
- Relay nodes, connections, global IDs, interfaces, and unions are part of the client contract.
- Your team is comfortable making query cost, authorization, and batching explicit in resolver code.
- You prefer schema-first GraphQL with SDL as the source of truth; Graphene's class metaprogramming makes Python declarations primary.
- Static typing must describe the public library itself; our installed wheel had no py.typed marker.
- You expect GraphQL to batch database access automatically; resolvers can still create an N+1 query for every returned row.
- You need an HTTP server out of the box; Graphene builds and executes schemas, while transport comes from Django, ASGI, Flask, or another integration.
- You want a fast release cadence for the core package; 3.4.3 was published in November 2024 and is still the current PyPI release.
Setup reality
Our fresh Python 3.12 install of Graphene 3.4.3 finished in 0.2 seconds and left 6 packages using 3 MB. import graphene completed in 0.75 seconds. The package is pure Python, reports 19 direct dependencies in our measurement, and our pip-audit run found 0 known vulnerabilities. PyPI does not declare a Python requirement, and the installed package had no py.typed marker.
Graphene creates a schema, not a web endpoint. Wire Schema into a framework integration, then decide where request context, authentication, and database sessions live. Resolver names default from fields, and Graphene converts snake_case Python names to camelCase GraphQL names unless auto_camelcase is disabled. That default can surprise an existing API contract.
Each resolver receives parent and info. Authentication usually comes from info.context, but field authorization remains application code. A resolver that loads a relationship once per parent creates N+1 database calls, so add a request-scoped DataLoader or push batching into the integration. Async resolvers need an async execution path and compatible transport.
GraphQL validation does not cap query depth, aliases, or execution cost by itself. Add limits before exposing a public endpoint, keep introspection policy deliberate, and return GraphQL errors without leaking internal exceptions. Version 3.4.3 specifically repairs invalid UUID input handling. Our import succeeded, but that says nothing about the framework, database integration, or resolver behavior you choose around the schema.
Patterns
Define and execute a small query define-query
import graphene
class Query(graphene.ObjectType):
greeting = graphene.String(name=graphene.String(default_value="world"))
def resolve_greeting(root, info, name):
return f"Hello, {name}"
schema = graphene.Schema(query=Query)Schema.execute is synchronous. Use execute_async when any resolver awaits I/O and the surrounding server can await the result.
Read request state inside a resolver execute-query
result = schema.execute(
"query($name: String) { greeting(name: $name) }",
variable_values={"name": "Mina"},
context_value={"user": current_user},
)
if result.errors:
raise RuntimeError("; ".join(str(error) for error in result.errors))
print(result.data)Pass context_value for each request. Treat context as request-scoped state rather than a global container shared between users.
Accept typed arguments on a field run-async-resolver
class Query(graphene.ObjectType):
account = graphene.Field(Account, id=graphene.ID(required=True))
async def resolve_account(root, info, id):
return await info.context["accounts"].get(id)
result = await graphene.Schema(query=Query).execute_async(
"{ account(id: \"42\") { name } }",
context_value=context,
)Graphene exposes Python snake_case names as camelCase by default. Disable auto_camelcase if the public schema must keep underscores.
Create a mutation with an output payload define-mutation
class RenameAccount(graphene.Mutation):
class Arguments:
account_id = graphene.ID(required=True)
name = graphene.String(required=True)
account = graphene.Field(Account)
def mutate(root, info, account_id, name):
account = rename_account(account_id, name)
return RenameAccount(account=account)
class Mutation(graphene.ObjectType):
rename_account = RenameAccount.Field()A mutation resolver still owns authorization, validation beyond GraphQL types, transaction boundaries, and error mapping.
Return one of several object types accept-input-object
class AccountInput(graphene.InputObjectType):
name = graphene.String(required=True)
timezone = graphene.String()
class CreateAccount(graphene.Mutation):
class Arguments:
values = AccountInput(required=True)
account = graphene.Field(Account)
def mutate(root, info, values):
return CreateAccount(account=create_account(**dict(values)))A Union needs concrete member types, and runtime resolution must identify which member each returned value represents.
Expose a Relay node lookup disable-auto-camelcase
class Query(graphene.ObjectType):
account_status = graphene.String()
schema = graphene.Schema(
query=Query,
auto_camelcase=False,
)
# Client field is account_status, not accountStatus.Relay global IDs encode a type and local ID rather than hiding access. Check authorization again after decoding the identifier.
Batch repeated resolver loads implement-relay-node
from graphene import relay
class Account(graphene.ObjectType):
class Meta:
interfaces = (relay.Node,)
name = graphene.String()
@classmethod
def get_node(cls, info, id):
return load_account(id)
class Query(graphene.ObjectType):
node = relay.Node.Field()Create loaders per request so cached records and permissions cannot leak across users. Batching addresses the common N+1 resolver pattern.
Run an async resolver batch-related-records
from aiodataloader import DataLoader
class UserLoader(DataLoader):
async def batch_load_fn(self, ids):
rows = await fetch_users(ids)
by_id = {row.id: row for row in rows}
return [by_id.get(id) for id in ids]
async def resolve_owner(root, info):
return await info.context["user_loader"].load(root.owner_id)Call execute_async and use an async-capable transport. Calling the synchronous execution method will not await this resolver correctly.
Return structured GraphQL errors export-schema-sdl
schema = graphene.Schema(query=Query, mutation=Mutation)
with open("schema.graphql", "w", encoding="utf-8") as file:
file.write(str(schema))GraphQLError extensions can carry a stable machine code. Avoid putting stack traces, SQL, or private exception messages into client responses.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| strawberry-graphql | PyPI | Choose it for a type-annotation and dataclass-oriented GraphQL API with first-class async patterns. |
| ariadne | PyPI | Choose it when SDL should define the schema and Python functions should attach to named fields. |
| graphql-core | PyPI | Choose the lower-level GraphQL implementation when you want direct control without Graphene's class layer. |
More web backend guides
urllib3 · requests · ws · anyio · httpx · undici · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.