Skip to main content

GraphQL implementation for Python, a port of GraphQL.js, the JavaScript reference implementation for GraphQL.

Project description

GraphQL-core 3

GraphQL-core 3 is a Python 3.6+ port of GraphQL.js, the JavaScript reference implementation for GraphQL, a query language for APIs created by Facebook.

PyPI version Documentation Status Build Status Coverage Status Dependency Updates Python 3 Status Code Style

The current version 3.1.2 of GraphQL-core is up-to-date with GraphQL.js version 15.1.0.

An extensive test suite with over 2200 unit tests and 100% coverage comprises a replication of the complete test suite of GraphQL.js, making sure this port is reliable and compatible with GraphQL.js.


A more detailed documentation for GraphQL-core 3 can be found at

The documentation for GraphQL.js can be found at

The documentation for GraphQL itself can be found at

There will be also blog articles with more usage examples.

Getting started

An overview of GraphQL in general is available in the README for the Specification for GraphQL. That overview describes a simple set of GraphQL examples that exist as tests in this repository. A good way to get started with this repository is to walk through that README and the corresponding tests in parallel.


GraphQL-core 3 can be installed from PyPI using the built-in pip command:

python -m pip install "graphql-core>=3"

Alternatively, you can also use pipenv for installation in a virtual environment:

pipenv install "graphql-core>=3"


GraphQL-core provides two important capabilities: building a type schema, and serving queries against that type schema.

First, build a GraphQL type schema which maps to your code base:

from graphql import (
    GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)

schema = GraphQLSchema(
            'hello': GraphQLField(
                resolve=lambda obj, info: 'world')

This defines a simple schema with one type and one field, that resolves to a fixed value. The resolve function can return a value, a co-routine object or a list of these. It takes two positional arguments; the first one provides the root or the resolved parent field, the second one provides a GraphQLResolveInfo object which contains information about the execution state of the query, including a context attribute holding per-request state such as authentication information or database session. Any GraphQL arguments are passed to the resolve functions as individual keyword arguments.

Note that the signature of the resolver functions is a bit different in GraphQL.js, where the context is passed separately and arguments are passed as a single object. Also note that GraphQL fields must be passed as a GraphQLField object explicitly. Similarly, GraphQL arguments must be passed as GraphQLArgument objects.

A more complex example is included in the top level tests directory.

Then, serve the result of a query against that type schema.

from graphql import graphql_sync

query = '{ hello }'

print(graphql_sync(schema, query))

This runs a query fetching the one field defined, and then prints the result:

ExecutionResult(data={'hello': 'world'}, errors=None)

The graphql_sync function will first ensure the query is syntactically and semantically valid before executing it, reporting errors otherwise.

from graphql import graphql_sync

query = '{ BoyHowdy }'

print(graphql_sync(schema, query))

Because we queried a non-existing field, we will get the following result:

ExecutionResult(data=None, errors=[GraphQLError(
    "Cannot query field 'BoyHowdy' on type 'RootQueryType'.",
    locations=[SourceLocation(line=1, column=3)])])

The graphql_sync function assumes that all resolvers return values synchronously. By using coroutines as resolvers, you can also create results in an asynchronous fashion with the graphql function.

import asyncio
from graphql import (
    graphql, GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)

async def resolve_hello(obj, info):
    await asyncio.sleep(3)
    return 'world'

schema = GraphQLSchema(
            'hello': GraphQLField(

async def main():
    query = '{ hello }'
    print('Fetching the result...')
    result = await graphql(schema, query)

loop = asyncio.get_event_loop()

Goals and restrictions

GraphQL-core tries to reproduce the code of the reference implementation GraphQL.js in Python as closely as possible and to stay up-to-date with the latest development of GraphQL.js.

GraphQL-core 3 (formerly known as GraphQL-core-next) has been created as a modern alternative to GraphQL-core 2, a prior work by Syrus Akbary, based on an older version of GraphQL.js and also targeting older Python versions. Some parts of GraphQL-core 3 have been inspired by GraphQL-core 2 or directly taken over with only slight modifications, but most of the code has been re-implemented from scratch, replicating the latest code in GraphQL.js very closely and adding type hints for Python.

Design goals for the GraphQL-core 3 library are:

  • to be a simple, cruft-free, state-of-the-art implementation of GraphQL using current library and language versions
  • to be very close to the GraphQL.js reference implementation, while still using a Pythonic API and code style
  • to make extensive use of Python type hints, similar to how GraphQL.js makes uses Flow
  • to use black for automatic code formatting
  • to replicate the complete Mocha-based test suite of GraphQL.js using pytest

Some restrictions (mostly in line with the design goals):

  • requires Python 3.6 or newer
  • does not support some already deprecated methods and options of GraphQL.js
  • supports asynchronous operations only via (does not support the additional executors in GraphQL-core)

Integration with other libraries and roadmap

  • Graphene is a more high-level framework for building GraphQL APIs in Python, and there is already a whole ecosystem of libraries, server integrations and tools built on top of Graphene. Most of this Graphene ecosystem has also been created by Syrus Akbary, who meanwhile has handed over the maintenance and future development to members of the GraphQL-Python community.

    The current version 2 of Graphene is using Graphql-core 2 as core library for much of the heavy lifting. Note that Graphene 2 is not compatible with GraphQL-core 3. The new version 3 of Graphene will use GraphQL-core 3 instead of GraphQL-core 2.

  • Ariadne is a Python library for implementing GraphQL servers using schema-first approach created by Mirumee Software.

    Ariadne is already using GraphQL-core 3 as its GraphQL implementation.

  • Strawberry, created by Patrick Arminio, is a new GraphQL library for Python 3, inspired by dataclasses, that is also using GraphQL-core 3 as underpinning.


Changes are tracked as GitHub releases.

Credits and history

The GraphQL-core 3 library

  • has been created and is maintained by Christoph Zwerschke
  • uses ideas and code from GraphQL-core 2, a prior work by Syrus Akbary
  • is a Python port of GraphQL.js which has been developed by Lee Byron and others at Facebook, Inc. and is now maintained by the GraphQL foundation

Please watch the recording of Lee Byron's short keynote on the history of GraphQL at the open source leadership summit 2019 to better understand how and why GraphQL was created at Facebook and then became open sourced and ported to many different programming languages.


GraphQL-core 3 is MIT-licensed, just like GraphQL.js.

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for graphql-core, version 3.1.2
Filename, size File type Python version Upload date Hashes
Filename, size graphql_core-3.1.2-py3-none-any.whl (183.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size graphql-core-3.1.2.tar.gz (487.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page