Install & Compatibility
Where this runs
tested against v1.3.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Upload
✓ from graphene_file_upload.scalars import Upload
✗ from graphene_file_upload import Upload
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.
import graphene
from graphene_file_upload.scalars import Upload
from graphene_file_upload.django import FileUploadGraphQLView
import os # For example file handling
class UploadFileMutation(graphene.Mutation):
class Arguments:
file = Upload(required=True)
success = graphene.Boolean()
file_name = graphene.String()
file_size = graphene.Int()
def mutate(self, info, file, **kwargs):
# `file` is a Django InMemoryUploadedFile or TemporaryUploadedFile object
# `info.context.FILES` also contains the uploaded files
# Example: Save the file to a temporary location or process it
upload_dir = 'uploads'
os.makedirs(upload_dir, exist_ok=True)
file_path = os.path.join(upload_dir, file.name)
with open(file_path, 'wb+') as destination:
for chunk in file.chunks():
destination.write(chunk)
return UploadFileMutation(
success=True,
file_name=file.name,
file_size=file.size
)
class Query(graphene.ObjectType):
hello = graphene.String(name=graphene.String(default_value="stranger"))
def resolve_hello(self, info, name):
return "Hello " + name
class Mutation(graphene.ObjectType):
upload_file = UploadFileMutation.Field()
schema = graphene.Schema(query=Query, mutation=Mutation)
# --- Django urls.py example (assuming you have a Django project setup) ---
# from django.urls import path
# from .schema import schema
#
# urlpatterns = [
# path(
# 'graphql/',
# FileUploadGraphQLView.as_view(schema=schema, graphiql=True)
# ),
# ]
#
# --- Flask app.py example (assuming you have a Flask app setup) ---
# from flask import Flask
# from .schema import schema # assuming schema is in a schema.py file
#
# app = Flask(__name__)
# app.add_url_rule(
# '/graphql',
# view_func=FileUploadGraphQLView.as_view(schema=schema, graphiql=True)
# )
Debug
Known issues
gotchaIt 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.fixEnsure your URL routing explicitly uses `FileUploadGraphQLView.as_view(...)` instead of `GraphQLView.as_view(...)`.
affects: All versions
deprecatedWhen 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.fixUpgrade `flask-graphql` to version 2.0 or newer: `pip install 'flask-graphql>=2.0'`
affects: < 1.0 (for flask-graphql)
gotchaClient-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.fixWhen 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.
affects: All versions
Upgrade
Version history
1.3.0latest on PyPI · released Feb 20, 2021
Audit
Dependencies
graphenerequiredCore GraphQL framework, required for the 'Upload' scalar type.
graphene-djangooptionalRequired for Django integration (FileUploadGraphQLView for Django).
flask-graphqloptionalRequired for Flask integration (FileUploadGraphQLView for Flask); Note: flask-graphql version <2.0 is not supported.