django-graphex

GraphQL for Django, powered by graphql-core and Pydantic. Define your GraphQL API straight from your Django models — no DRF, no graphene, no django-filter.

• Model-first types & mutations — DjangoModelType / DjangoModelMutation give you query, list and create/update/delete from a single Meta.model, validated and persisted with Pydantic v2 + the Django ORM (FK existence, uniqueness, unique_together, partial updates, choices → Enum).
• Logical filtering — one nested filter: argument with and / or / not, per-field lookups, relation descent and plain-pk/UUID filtering (no django-filter).
• Pagination — limit/offset, page and keyset cursor paginators with a uniform results / totalCount shape (and an automatic N+1 query optimizer).
• Custom validation — DRF-style inline validate_<field>() / validate() or a Meta.pydantic_model.
• Permissions, security & directives — permission classes, depth & cost limits, introspection control, and string/number/date/list directives. Meta.only_fields / Meta.exclude_fields are a security boundary: a column a type hides is unreadable, unorderable and unfilterable through it.
• Subscriptions — real-time GraphQL over Django Channels 4 (optional extra).

Coming from graphene-django or graphene-django-extras? See the Migration Guide for a step-by-step upgrade with before/after examples.

Upgrading from django-graphex 1.x? 2.0 removed the graphene backend entirely — see the Upgrade Guide and the scripts/migrate_2_0.py codemod.

Requirements

• Python: 3.12+ (3.13, 3.14 supported)
• Django: 5.2+ (5.2 LTS, 6.0 supported) — each Django version tested on the Python versions it officially supports
• graphql-core: >=3.2.11,<3.3
• pydantic: >=2,<3

Installation

# uv (recommended)
uv add django-graphex
# real-time subscriptions (adds Django Channels 4):
uv add "django-graphex[subscriptions]"

# pip
pip install django-graphex
pip install "django-graphex[subscriptions]"

The base install never imports channels; only the subscriptions extra does.

Quick start

from django.contrib.auth.models import User
from django_graphex.fields import DjangoListObjectField
from django_graphex.mutation import DjangoModelMutation
from django_graphex.core import ObjectType
from django_graphex.paginations import LimitOffsetGraphqlPagination
from django_graphex.schema import DjangoGraphQLSchema
from django_graphex.types import DjangoListObjectType


class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination()
        filter_fields = {"username": ("icontains", "exact"), "is_active": ("exact",)}


class UserMutation(DjangoModelMutation):      # define once -> create/update/delete
    class Meta:
        model = User


class Query(ObjectType):
    users = DjangoListObjectField(UserListType)


class Mutation(ObjectType):
    user_create = UserMutation.CreateField()
    user_update = UserMutation.UpdateField()
    user_delete = UserMutation.DeleteField()


schema = DjangoGraphQLSchema(query=Query, mutation=Mutation)

Query it with the nested filter: argument (and / or / not):

{
  users(filter: { isActive: { exact: true }, username: { icontains: "jo" } }) {
    results(limit: 10, ordering: "-date_joined") { id username }
    totalCount
  }
}

Configuration

All settings live under a single DJANGO_GRAPHEX dict (every key is optional):

# settings.py
DJANGO_GRAPHEX = {
    "DEFAULT_PAGINATION_CLASS": "django_graphex.paginations.LimitOffsetGraphqlPagination",
    "DEFAULT_PAGE_SIZE": 20,
    "MAX_PAGE_SIZE": 50,
    # Response caching. Default is False (disabled).
    # WARNING: cache keys are identity-salted per user (v1.2.1+), but shared
    # caches can still leak data if misconfigured. Review the caching guide
    # before enabling in production: docs/usage/caching.md
    "CACHE_ACTIVE": True,
}

Two keys are not in that dict on purpose — both ship enabled, and pinning a key to its own default only hides that you depend on it:

• REQUIRE_CSRF_HEADER (True) demands an X-Requested-With header on form-encoded and multipart/form-data POSTs, which a browser can send cross-site with no CORS preflight. application/json clients are unaffected; form-encoded and multipart clients get HTTP 403 without it.
• MAX_SUBSCRIPTIONS_PER_CONNECTION (50) caps the concurrent operations one graphql-transport-ws socket may hold.

Both are documented in Settings, and both are breaking for clients written against 2.2.0.

To use directives, add the middleware and pass all_directives to the schema:

DJANGO_GRAPHEX = {"MIDDLEWARE": ["django_graphex.middleware.GraphQLDirectiveMiddleware"]}

from django_graphex.directives import all_directives
from django_graphex.schema import DjangoGraphQLSchema
schema = DjangoGraphQLSchema(query=Query, mutation=Mutation, directives=all_directives)

Playground

A fully wired example project lives in examples/playground/. It exercises every major feature end-to-end — types, paginators, filtering, mutations, permissions, subscriptions, file uploads on both paths, the projection boundary on all three axes, and the query optimizer — and installs the library from this repo checkout (editable, no PyPI release needed). make test runs 51 end-to-end tests, several of which assert the verbatim answer strings its README quotes.

Documentation

📚 Full documentation — including the Quick Start, Model backend, Filtering, Pagination, Subscriptions, Settings and the Migration Guide.

License

MIT License — see the LICENSE file.