Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.566s · 68MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 2.1s · import 0.506s · 26MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GraphQLApp
✓ from starlette_graphene3 import GraphQLApp
✗ from starlette.graphql import GraphQLApp
Starlette's built-in GraphQLApp was deprecated in Starlette 0.15.0 and removed in 0.17.0, requiring migration to third-party libraries like starlette-graphene3 for Graphene v3 support.
make_graphiql_handler
✓ from starlette_graphene3 import make_graphiql_handler
Used to serve the GraphiQL interactive IDE for GraphQL queries.
This quickstart demonstrates setting up a basic Starlette application with GraphQL using `starlette-graphene3`. It defines a simple query and a subscription, then mounts the `GraphQLApp` at the root path with the GraphiQL handler enabled for an interactive interface.
import asyncio
import graphene
from starlette.applications import Starlette
from starlette_graphene3 import GraphQLApp, make_graphiql_handler
class User(graphene.ObjectType):
id = graphene.ID()
name = graphene.String()
class Query(graphene.ObjectType):
me = graphene.Field(User)
def resolve_me(root, info):
# In a real app, this would fetch data from a database or service
return User(id="1", name="Test User")
class Subscription(graphene.ObjectType):
count = graphene.Int(upto=graphene.Int())
async def subscribe_count(root, info, upto=3):
for i in range(upto):
yield i
await asyncio.sleep(1)
app = Starlette()
schema = graphene.Schema(query=Query, subscription=Subscription)
app.mount("/", GraphQLApp(schema, on_get=make_graphiql_handler()))
# To run this example, save it as `main.py` and execute:
# uvicorn main:app --reload
# Then open your browser to http://127.0.0.1:8000/
Debug
Known issues
breakingStarlette's native GraphQLApp was removed in Starlette 0.17.0 (deprecated in 0.15.0). Applications relying on `from starlette.graphql import GraphQLApp` must migrate to third-party libraries like `starlette-graphene3` for Graphene v3 support.fixReplace `from starlette.graphql import GraphQLApp` with `from starlette_graphene3 import GraphQLApp` and ensure your Graphene schema is compatible with Graphene v3.
affects: Starlette >=0.15.0
gotchaWhen integrating with FastAPI, older versions (e.g., FastAPI 0.63.0) might have strict Starlette dependency requirements (e.g., `starlette==0.13.6`) that conflict with `starlette-graphene3`'s requirement (`starlette>=0.14.1`).fixUpgrade FastAPI to a newer version that allows a compatible Starlette range, or carefully manage your `starlette` dependency to satisfy both libraries. Using a newer FastAPI is generally recommended.
affects: FastAPI <0.68.0 (approx), starlette-graphene3 all versions
gotchaFor GraphQL file upload functionality, the `python-multipart` library must be installed separately. The base `starlette-graphene3` installation does not include it.fixRun `pip install 'starlette-graphene3[all]'` or `pip install python-multipart` alongside `starlette-graphene3`.
affects: all
gotchaAsynchronous resolvers (defined with `async def`) in Graphene 3 require proper handling of the awaitable return value in custom middleware or field resolvers, otherwise they might not execute correctly or lead to `TypeError: Cannot return null for non-nullable field` issues.fixEnsure that custom Graphene execution logic correctly awaits coroutine objects returned by resolvers. The default `GraphQLApp` should handle this correctly, but custom executors or resolvers might need explicit `await` calls if they override core behavior.
affects: Graphene v3 (all versions used by starlette-graphene3)
Errors
Common errors & fixes
ERROR: fastapi X.Y.Z has requirement starlette==A.B.C, but you'll have starlette D.E.F which is incompatible.
A version mismatch between FastAPI's required Starlette version and the version required by `starlette-graphene3`.
fixUpdate FastAPI and `starlette-graphene3` to their latest compatible versions. Check the dependency trees (e.g., `pip check` or inspect `pyproject.toml` files) to find compatible ranges. Often, upgrading FastAPI resolves this.
TypeError: Cannot return null for non-nullable field X.id.
This error often occurs when an asynchronous Graphene resolver is not properly awaited, causing a `Coroutine` object to be returned where a concrete value is expected, or if a non-nullable field indeed returns `None`.
fixVerify that all asynchronous resolvers are `await`ed correctly within the execution context. If writing custom execution logic, ensure `inspect.isawaitable()` is used and `await` is applied. Also, double-check that non-nullable fields genuinely return a value and not `None`.
Upgrade
Version history
0.6.0latest on PyPI · released Jun 1, 2022
Audit
Dependencies
graphenerequiredCore GraphQL library for defining schemas, types, queries, mutations, and subscriptions.
graphql-corerequiredRequired by Graphene for GraphQL execution.
starletterequiredASGI web framework that this library integrates with.
python-multipartoptionalEnables file uploading functionality through GraphQL.
uvicornoptionalA highly performant ASGI server commonly used to run Starlette applications in development and production.