Install & Compatibility
Where this runs
tested against v3.2.3 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 74.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.3s · import 0.000s · 75MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DjangoObjectType
✓ from graphene_django.types import DjangoObjectType
✗ from graphene_django import DjangoObjectType
This example shows how to expose a Django model through a GraphQL API using `graphene-django`. It defines a simple `Category` model, creates a `DjangoObjectType` for it, and exposes `all_categories` via a `DjangoConnectionField` for Relay-compliant pagination. It also demonstrates how to fetch a single category by ID. Remember to configure your Django `urls.py` with `GraphQLView` and add `graphene_django` to your `INSTALLED_APPS`.
import graphene
from graphene_django.types import DjangoObjectType
from graphene_django.fields import DjangoConnectionField
from django.db import models
# 1. Define a Django Model (e.g., in myapp/models.py)
class Category(models.Model):
name = models.CharField(max_length=100)
class Meta:
# Essential for Relay Connection in Django 5+ to ensure consistent ordering
ordering = ['name']
def __str__(self):
return self.name
# 2. Define a Graphene DjangoObjectType (e.g., in myapp/schema.py)
class CategoryType(DjangoObjectType):
class Meta:
model = Category
# Explicitly list fields for clarity/control, or use '__all__'
fields = ('id', 'name')
# 3. Define a Query (e.g., in myapp/schema.py)
class Query(graphene.ObjectType):
all_categories = DjangoConnectionField(CategoryType)
# Optionally, resolve a single category by ID
category = graphene.Field(CategoryType, id=graphene.ID())
def resolve_category(root, info, id):
try:
return Category.objects.get(pk=id)
except Category.DoesNotExist:
return None
# 4. Create the Graphene Schema (e.g., in myapp/schema.py)
schema = graphene.Schema(query=Query)
# 5. Integrate into Django URLs (e.g., in project/urls.py)
# from django.urls import path
# from graphene_django.views import GraphQLView
# from myapp.schema import schema # Assuming myapp/schema.py
# urlpatterns = [
# path('graphql/', GraphQLView.as_view(graphiql=True, schema=schema)),
# ]
# Remember to add 'graphene_django' to INSTALLED_APPS in your Django settings.py
Debug
Known issues
breakingGraphene Django v3 introduced significant breaking changes from v2. Key changes include moving `Node` to `graphene_django.types.Node` and changes in how `DjangoFilterConnectionField` defaults are handled. Ensure your code is updated to use v3 import paths and configurations.fixReview the official Graphene Django v3 upgrade guide for a comprehensive list of changes. Update import paths (e.g., `from graphene_django.types import Node`) and adapt custom filters/resolvers.
affects: >=3.0.0
gotchaWhen using `DjangoConnectionField` for Relay connections, the underlying Django model's `Meta` options (e.g., `ordering` or `get_latest_by`) or the `DjangoObjectType`'s `Meta.order_by` must explicitly define a default ordering. Failing to do so can result in errors, especially with newer Django versions (5.x and above) where this check became more strict.fixAdd `class Meta: ordering = ['your_field']` to your Django model or `DjangoObjectType` to specify a default order for connections.
affects: >=3.2.1, Django >= 5.0
gotchaTo use `DjangoFilterConnectionField` for filtering connections, you must explicitly install the `django-filter` package in addition to `graphene-django`. This is not an automatic dependency.fixRun `pip install django-filter` and add `'django_filters'` to your `INSTALLED_APPS` in `settings.py` to enable filtering capabilities with `DjangoFilterConnectionField`.
affects: all
gotchaHandling Django model `choices` fields as Graphene `Enum` types can be complex, particularly when dealing with different Django versions or specific ORM behaviors. The automatic conversion might not always align with expectations, and custom handling might be required.fixReview the `Graphene-Django` documentation on `choices` fields. For specific issues, consider defining your `Enum` explicitly in Graphene and mapping it manually, or utilizing the `GRAPHENE_DJANGO` setting `convert_choices_to_enums` for global control.
affects: all
Upgrade
Version history
3.2.3latest on PyPI · released Mar 13, 2025
Audit
Dependencies
graphenerequiredCore GraphQL framework dependency.
DjangorequiredRequired for integration with Django projects.
django-filteroptionalOptional, required for DjangoFilterConnectionField to enable filtering on connections.