GraphQL-core 3 is a Python port of GraphQL.js, the JavaScript reference implementation for GraphQL, a query language for APIs created by Facebook. It provides a faithful and up-to-date implementation of the GraphQL specification for current Python versions, including schema definition, parsing, validation, and execution. The library maintains an active release cadence, issuing stable patch releases alongside ongoing alpha development for future major versions.
Install & Compatibility
Where this runs
tested against v3.2.8 · 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.925 runs
installs and imports cleanly · install 0.0s · import 0.337s · 19.8MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.7s · import 0.296s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GraphQLSchema
✓ from graphql import GraphQLSchema
GraphQLObjectType
✓ from graphql import GraphQLObjectType
GraphQLField
✓ from graphql import GraphQLField
GraphQLString
✓ from graphql import GraphQLString
graphql_sync
✓ from graphql import graphql_sync
✗ from graphql.execution.execute import execute
The `graphql_sync` function from the top-level `graphql` package is the recommended entry point for synchronous execution, replacing older `execute` patterns from `graphql.execution.execute`.
This quickstart demonstrates how to define a simple GraphQL schema with a 'hello' field that resolves to 'world', and then execute a query against it using `graphql_sync`.
from graphql import (
GraphQLSchema,
GraphQLObjectType,
GraphQLField,
GraphQLString,
graphql_sync
)
# 1. Define your GraphQL schema
schema = GraphQLSchema(
query=GraphQLObjectType(
name='RootQueryType',
fields={
'hello': GraphQLField(
GraphQLString,
resolve=lambda obj, info: 'world'
)
}
)
)
# 2. Define a GraphQL query
source = '{ hello }'
# 3. Execute the query synchronously
result = graphql_sync(schema, source)
# 4. Print the result
print(result.data['hello']) # Expected: world
Debug
Known issues
breakingThe upcoming v3.3.x series (currently in alpha) will drop support for Python 3.7, 3.8, and 3.9. It will require Python 3.10 or newer.fixEnsure your project runs on Python 3.10+ before upgrading to `graphql-core` v3.3.x.
affects: >=3.3.0a1
breakingIn v3.3.0a12, AST collection fields have been changed from mutable lists to immutable tuples for better type safety and immutability.fixUpdate any code that relies on mutating AST collection fields as lists to treat them as immutable tuples. Access elements by index, but avoid in-place modifications.
affects: >=3.3.0a12
breakingThe alias `introspection.TypeResolvers` was backported to v3.2.8 for backward compatibility. It's likely to be removed or significantly changed in v3.3.x, which would break direct usage.fixMigrate any code using `introspection.TypeResolvers` to `introspection.TypeFields` (or its equivalent in the v3.3.x branch) to ensure future compatibility.
affects: >=3.3.0a1 (future stable)
gotchaGraphQL-core does not follow SemVer directly. Changes in the major version of `GraphQL.js` are reflected in the *minor* version of `graphql-core`. This means minor version bumps (`3.x.0` to `3.y.0`) can introduce breaking API changes.fixPin your `graphql-core` dependency using a compatible release operator like `~=3.2.0` (for 3.2.x releases) to avoid unexpected breaking changes on minor version upgrades.
affects: All versions
gotchaResolver function signatures in `graphql-core` differ from `GraphQL.js`. In Python, arguments are passed as individual keyword arguments, whereas in `GraphQL.js`, they are often passed as a single arguments object.fixBe mindful of resolver signature expectations when porting examples or logic from JavaScript-based GraphQL implementations. The Python resolver typically takes `obj, info, **kwargs` where `kwargs` are the GraphQL arguments.
affects: All versions
gotchaWhen defining schemas programmatically, GraphQL fields and arguments must be explicitly passed as `GraphQLField` and `GraphQLArgument` objects, respectively.fixAlways wrap field definitions with `GraphQLField()` and argument definitions with `GraphQLArgument()` when constructing schemas in Python code.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'graphql-core'
The 'graphql-core' package is not installed in your Python environment or is not accessible in the current path.
fixpip install graphql-core
Cannot query field "username" on type "User"
The GraphQL query is attempting to request a field (e.g., 'username') that is not defined in the schema for the specified type (e.g., 'User').
fixEnsure your GraphQL schema defines the 'username' field on the 'User' type, or modify your query to request an existing field from the 'User' type.
TypeError: 'NoneType' object is not callable
A GraphQL resolver for a field is returning `None` when the execution engine expects a callable function, a value that can be directly resolved, or an iterable, leading to an attempt to call `None`.
fixEnsure that your resolver functions explicitly return the correct data type or a callable, and handle cases where data might legitimately be `None` by defining the field as nullable in your schema if appropriate.
Expected type Int, found "abc"
An input argument or variable in a GraphQL query or mutation is receiving a value of a different type than what the schema expects (e.g., a string 'abc' instead of an integer).
fixProvide a value that matches the expected type defined in your GraphQL schema for the argument or variable (e.g., pass an actual integer for an `Int` type).
Audit
Dependencies
pythonrequiredRequires Python 3.7+ for v3.2.x. Future v3.3.x will require Python 3.10+.