{"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":"python","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":[{"wrong":"from graphene_file_upload import Upload","symbol":"Upload","correct":"from graphene_file_upload.scalars import Upload"}],"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,"search_vec":"'1.3.0':56 '2021':74 'act':32 'adher':45 'cadenc':66 'current':53 'django':17,80 'drop':36 'drop-in':35 'earli':73 'enabl':23 'extend':13 'file':2,6,25,77 'file-upload':76 'fix':65 'flask':20,81 'flask-graphql':19 'function':27 'graphen':1,5,14,16,79 'graphene-django':15 'graphene-file-upload':4 'graphql':21,29,42,48,75 'last':68 'librari':11 'multipart':49 'mutat':30 'occur':59 'period':60 'python':10 'releas':58 'replac':38 'request':50 'robust':24 'signific':69 'specif':51 'standard':41 'updat':70 'upload':3,7,26,78 'version':54 'view':43","created_at":"2026-04-16T13:51:21.126212+00:00","updated_at":"2026-04-16T13:51:21.126212+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmp233tpptk/venv/lib/python3.12/site-packages/graphene_file_upload/scalars.py\", line 5, in <module>\n    import graphene\nModuleNotFoundError: No module named 'graphene'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/lmcgartland/graphene-file-upload","docs":null,"changelog":null,"pypi":"https://pypi.org/project/graphene-file-upload/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}