{"id":7277,"library":"graphene-file-upload","title":"Graphene File Upload","description":"graphene-file-upload is a Python library that extends Graphene, Graphene-Django, and Flask-GraphQL to enable robust file upload functionality in GraphQL mutations. It acts as a drop-in replacement for the standard GraphQL view and adheres to the GraphQL Multipart Request Specification. The current version is 1.3.0, with releases occurring periodically but not on a fixed cadence, the last significant update being in early 2021.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/lmcgartland/graphene-file-upload","tags":["graphql","file-upload","graphene","django","flask"],"install":[{"cmd":"pip install graphene-file-upload","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core GraphQL framework, required for the 'Upload' scalar type.","package":"graphene","optional":false},{"reason":"Required for Django integration (FileUploadGraphQLView for Django).","package":"graphene-django","optional":true},{"reason":"Required for Flask integration (FileUploadGraphQLView for Flask); Note: flask-graphql version <2.0 is not supported.","package":"flask-graphql","optional":true}],"imports":[{"note":"The 'Upload' scalar type is provided by graphene-file-upload, not directly by Graphene core.","wrong":"from graphene.types.scalars import Upload","symbol":"Upload","correct":"from graphene_file_upload.scalars import Upload"},{"note":"Must replace the standard Graphene-Django GraphQLView with the file-upload-enabled version for multipart requests to be processed correctly.","wrong":"from graphene_django.views import GraphQLView","symbol":"FileUploadGraphQLView (Django)","correct":"from graphene_file_upload.django import FileUploadGraphQLView"},{"note":"Must replace the standard Flask-GraphQL GraphQLView with the file-upload-enabled version.","wrong":"from flask_graphql import GraphQLView","symbol":"FileUploadGraphQLView (Flask)","correct":"from graphene_file_upload.flask import FileUploadGraphQLView"}],"quickstart":{"code":"import graphene\nfrom graphene_file_upload.scalars import Upload\nfrom graphene_file_upload.django import FileUploadGraphQLView\n\nimport os # For example file handling\n\nclass UploadFileMutation(graphene.Mutation):\n    class Arguments:\n        file = Upload(required=True)\n\n    success = graphene.Boolean()\n    file_name = graphene.String()\n    file_size = graphene.Int()\n\n    def mutate(self, info, file, **kwargs):\n        # `file` is a Django InMemoryUploadedFile or TemporaryUploadedFile object\n        # `info.context.FILES` also contains the uploaded files\n        \n        # Example: Save the file to a temporary location or process it\n        upload_dir = 'uploads'\n        os.makedirs(upload_dir, exist_ok=True)\n        file_path = os.path.join(upload_dir, file.name)\n        with open(file_path, 'wb+') as destination:\n            for chunk in file.chunks():\n                destination.write(chunk)\n\n        return UploadFileMutation(\n            success=True,\n            file_name=file.name,\n            file_size=file.size\n        )\n\nclass Query(graphene.ObjectType):\n    hello = graphene.String(name=graphene.String(default_value=\"stranger\"))\n\n    def resolve_hello(self, info, name):\n        return \"Hello \" + name\n\nclass Mutation(graphene.ObjectType):\n    upload_file = UploadFileMutation.Field()\n\nschema = graphene.Schema(query=Query, mutation=Mutation)\n\n# --- Django urls.py example (assuming you have a Django project setup) ---\n# from django.urls import path\n# from .schema import schema\n#\n# urlpatterns = [\n#     path(\n#         'graphql/',\n#         FileUploadGraphQLView.as_view(schema=schema, graphiql=True)\n#     ),\n# ]\n#\n# --- Flask app.py example (assuming you have a Flask app setup) ---\n# from flask import Flask\n# from .schema import schema # assuming schema is in a schema.py file\n#\n# app = Flask(__name__)\n# app.add_url_rule(\n#     '/graphql',\n#     view_func=FileUploadGraphQLView.as_view(schema=schema, graphiql=True)\n# )","lang":"python","description":"This quickstart demonstrates how to define a GraphQL mutation that accepts a file upload using the `Upload` scalar. The `mutate` method receives the uploaded file object (e.g., `InMemoryUploadedFile` in Django). It then shows how to integrate this into a Django `urls.py` or Flask `app.py` by using `FileUploadGraphQLView` instead of the standard GraphQL view. The example includes basic file saving to a local 'uploads' directory."},"warnings":[{"fix":"Ensure your URL routing explicitly uses `FileUploadGraphQLView.as_view(...)` instead of `GraphQLView.as_view(...)`.","message":"It is critical to replace your standard `GraphQLView` (from `graphene_django.views` or `flask_graphql`) with `FileUploadGraphQLView` from `graphene_file_upload.django` or `graphene_file_upload.flask`. Failure to do so will result in the backend not correctly parsing multipart form data, leading to errors like 'Must provide query string.' or an empty `file` argument in your mutation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `flask-graphql` to version 2.0 or newer: `pip install 'flask-graphql>=2.0'`","message":"When using Flask-GraphQL, versions prior to 2.0 are not supported by `graphene-file-upload`. Ensure you are using `flask-graphql` version 2.0 or higher.","severity":"deprecated","affected_versions":"< 1.0 (for flask-graphql)"},{"fix":"When using `FormData` in JavaScript, typically omit setting the `Content-Type` header; let the browser handle it automatically to ensure correct boundary generation. If manually creating the multipart body, ensure `operations` and `map` fields are correctly formatted according to the GraphQL multipart request spec. Using client libraries like `apollo-upload-client` is recommended.","message":"Client-side `multipart/form-data` requests for file uploads can be tricky. If manually constructing a `fetch` request, explicitly setting the `Content-Type: multipart/form-data` header might cause issues with automatic boundary generation, leading to `MultiPartParserError` or the `file` argument being empty on the server.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"First, verify you are using `FileUploadGraphQLView` in your Django `urls.py`. Second, ensure your client-side code (e.g., JavaScript `fetch`) is constructing the `FormData` object correctly and is *not* explicitly setting the `Content-Type` header, allowing the browser to set it with the correct boundary.","cause":"The backend failed to parse the multipart/form-data request, often due to an incorrectly formatted `Content-Type` header or missing boundary information, or the wrong GraphQL view being used.","error":"django.http.multipartparser.MultiPartParserError: Invalid boundary in multipart: None"},{"fix":"Double-check that `FileUploadGraphQLView` is used in your Django/Flask `urls.py`/routing configuration. Also, review the client-side request; ensure the `file` is properly attached to the `FormData` and that `operations` and `map` fields in the multipart request are correctly defined if not using a dedicated upload client.","cause":"The uploaded file is not being correctly passed to the Graphene mutation. This typically happens if the `GraphQLView` is not correctly configured or the client-side request is malformed.","error":"info.context.FILES.items is empty / file argument in mutation is None"},{"fix":"Ensure you have correctly replaced the default `GraphQLView` with `FileUploadGraphQLView` in your application's URL routing (e.g., `urls.py` for Django or `app.add_url_rule` for Flask).","cause":"This error occurs when the GraphQL server (specifically the standard Graphene `GraphQLView`) expects a JSON body with a `query` field, but it receives a `multipart/form-data` request that it cannot parse as a standard GraphQL query. This implies `FileUploadGraphQLView` is not active.","error":"{\"errors\":[{\"message\":\"Must provide query string.\"}]}"}]}