GraphQL-core

3.2.8 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install graphql-core

Common errors

error ModuleNotFoundError: No module named 'graphql-core' ↓

cause The 'graphql-core' package is not installed in your Python environment or is not accessible in the current path.

fix

pip install graphql-core

error Cannot query field "username" on type "User" ↓

cause 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').

fix

Ensure your GraphQL schema defines the 'username' field on the 'User' type, or modify your query to request an existing field from the 'User' type.

error TypeError: 'NoneType' object is not callable ↓

cause 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`.

fix

Ensure 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.

error Expected type Int, found "abc" ↓

cause 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).

fix

Provide 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).

Warnings

breaking The 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. ↓

fix Ensure your project runs on Python 3.10+ before upgrading to `graphql-core` v3.3.x.

breaking In v3.3.0a12, AST collection fields have been changed from mutable lists to immutable tuples for better type safety and immutability. ↓

fix Update 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.

breaking The 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. ↓

fix Migrate any code using `introspection.TypeResolvers` to `introspection.TypeFields` (or its equivalent in the v3.3.x branch) to ensure future compatibility.

gotcha GraphQL-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. ↓

fix Pin 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.

gotcha Resolver 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. ↓

fix Be 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.

gotcha When defining schemas programmatically, GraphQL fields and arguments must be explicitly passed as `GraphQLField` and `GraphQLArgument` objects, respectively. ↓

fix Always wrap field definitions with `GraphQLField()` and argument definitions with `GraphQLArgument()` when constructing schemas in Python code.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.20s 19.7M

3.10 slim (glibc) - - 0.13s 20M

3.11 alpine (musl) - - 0.32s 21.9M

3.11 slim (glibc) - - 0.26s 22M

3.12 alpine (musl) - - 0.50s 13.7M

3.12 slim (glibc) - - 0.47s 14M

3.13 alpine (musl) - - 0.50s 13.3M

3.13 slim (glibc) - - 0.47s 14M

3.9 alpine (musl) - - 0.18s 19.5M

3.9 slim (glibc) - - 0.17s 20M

Imports

GraphQLSchema
```
from graphql import GraphQLSchema
```
GraphQLObjectType
```
from graphql import GraphQLObjectType
```
GraphQLField
```
from graphql import GraphQLField
```
GraphQLString
```
from graphql import GraphQLString
```
graphql_sync
wrong
```
from graphql.execution.execute import execute
```
correct
```
from graphql import graphql_sync
```
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`.

Quickstart verified last tested: 2026-04-23

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