{"id":9793,"library":"graphql-server","title":"GraphQL Server for Python","description":"graphql-server is a Python library that provides integrations for setting up GraphQL servers in various web frameworks such as Flask, Starlette, Django, and Sanic. It currently includes version 3.0.0, which acts as a meta-package bundling core server logic and framework-specific adapters. Releases are made as needed, often in conjunction with updates to its underlying `graphql-core` and framework integration packages.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/graphql-python/graphql-server","tags":["graphql","server","api","http","framework-integration","flask","starlette","django"],"install":[{"cmd":"pip install graphql-server","lang":"bash","label":"Install all framework integrations"},{"cmd":"pip install graphql-server-starlette  # Or -flask, -django, etc.","lang":"bash","label":"Install specific framework integration"}],"dependencies":[{"reason":"Provides the core GraphQL execution logic.","package":"graphql-core","optional":false},{"reason":"Commonly used for building GraphQL schemas, though not a strict dependency of graphql-server itself.","package":"graphene","optional":true},{"reason":"Required for `graphql-server-starlette` integration.","package":"starlette","optional":true},{"reason":"Required for `graphql-server-flask` integration.","package":"flask","optional":true}],"imports":[{"note":"GraphQLRouter is specific to the Starlette integration. Attempting to import directly from the top-level `graphql_server` package will result in a ModuleNotFoundError as `graphql-server` is a meta-package.","wrong":"from graphql_server import GraphQLRouter","symbol":"GraphQLRouter","correct":"from graphql_server.starlette import GraphQLRouter"},{"note":"GraphQLView is specific to the Flask integration. Direct import from `graphql_server` is incorrect due to the meta-package structure.","wrong":"from graphql_server import GraphQLView","symbol":"GraphQLView","correct":"from graphql_server.flask import GraphQLView"},{"note":"This is a core utility for HTTP query execution, part of the `graphql-server-core` package, which is a dependency of `graphql-server`.","symbol":"run_http_query","correct":"from graphql_server_core.http import run_http_query"}],"quickstart":{"code":"import graphene\nfrom starlette.applications import Starlette\nfrom starlette.responses import JSONResponse\nfrom starlette.routing import Route\nfrom graphql_server.starlette import GraphQLRouter\n\n# 1. Define your GraphQL schema using Graphene\nclass Query(graphene.ObjectType):\n    hello = graphene.String(name=graphene.String(default_value=\"World\"))\n\n    def resolve_hello(self, info, name):\n        return f\"Hello, {name}!\"\n\nschema = graphene.Schema(query=Query)\n\n# 2. Integrate with Starlette using GraphQLRouter\nasync def homepage(request):\n    return JSONResponse({\"message\": \"Visit /graphql for the API or /graphql-playground for the UI.\"}) \n\nroutes = [\n    Route(\"/\", homepage),\n    Route(\"/graphql\", GraphQLRouter(schema)),\n    Route(\"/graphql-playground\", GraphQLRouter(schema, playground=True))\n]\n\napp = Starlette(routes=routes)\n\n# To run this app, save it as `app.py` and execute:\n# uvicorn app:app --reload\n# Then visit http://127.0.0.1:8000/graphql-playground in your browser.","lang":"python","description":"This quickstart demonstrates setting up a basic GraphQL server with Starlette and `graphql-server-starlette`. It defines a simple schema using `graphene`, then exposes it via `GraphQLRouter` at `/graphql` and a GraphQL Playground UI at `/graphql-playground`. You'll need `starlette`, `uvicorn`, `graphene`, and `graphql-server` installed."},"warnings":[{"fix":"Update your import statements to point to the correct framework-specific submodule, such as `graphql_server.flask`, `graphql_server.starlette`, or `graphql_server.django`.","message":"Version 3.x of `graphql-server` is a meta-package; direct imports like `from graphql_server import GraphQLView` are no longer valid. Instead, you must import from framework-specific submodules (e.g., `from graphql_server.flask import GraphQLView`).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For smaller deployments or to manage dependencies more precisely, install only the specific framework integration package you intend to use (e.g., `pip install graphql-server-starlette`).","message":"Installing `graphql-server` installs all framework integrations by default. If you only need one (e.g., for Flask), it's more efficient to install the specific package (e.g., `pip install graphql-server-flask`).","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always define a valid `graphene.Schema` object or similar schema representation and pass it to your `GraphQLView` or `GraphQLRouter` instance. Check `graphql-core` and `graphene` documentation for schema building best practices.","message":"GraphQL Server for Python relies on `graphql-core` for the underlying GraphQL implementation and `graphene` (or similar) for schema definition. Ensure these dependencies are correctly installed and your schema is properly constructed.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change the import to `from graphql_server.flask import GraphQLView` (for Flask) or `from graphql_server.starlette import GraphQLRouter` (for Starlette), etc., depending on your chosen framework.","cause":"Attempting to import `GraphQLView` (or `GraphQLRouter`) directly from the top-level `graphql_server` package, which is a meta-package and does not expose these symbols directly.","error":"ModuleNotFoundError: No module named 'graphql_server.GraphQLView'"},{"fix":"Ensure you have a valid `graphene.Schema(...)` object (or equivalent) and that it's correctly passed as the `schema` argument when initializing your GraphQL endpoint handler.","cause":"Often occurs when the GraphQL schema is not properly defined, instantiated, or passed as an argument to `GraphQLView` or `GraphQLRouter`.","error":"TypeError: 'NoneType' object is not callable"},{"fix":"Provide a `graphene.Schema` instance (e.g., `GraphQLRouter(schema=my_graphene_schema)`) or a schema path if using an alternative schema loading mechanism.","cause":"The `GraphQLView` or `GraphQLRouter` was instantiated without a valid GraphQL schema object or a path to a schema file.","error":"AssertionError: You must provide a 'schema' or 'schema_path' to GraphQLView."}]}