File uploads

Ariadne implements the GraphQL multipart request specification that describes how file uploads should be implemented by both API clients and servers.

Note

File uploads support for ASGI server requires that python-multipart is installed:

pip install ariadne[asgi-file-uploads]

Enabling file uploads

To enable file uploads on your server, define new a scalar named Upload in your schema:

scalar Upload

Next, import upload_scalar from ariadne package and use it during the creation of your executable schema:

from ariadne import make_executable_schema, upload_scalar

# ...your types definitions

schema = make_executable_schema(type_defs, [..., upload_scalar])

You will now be able to use Upload scalar arguments for your operations:

type Mutation {
    uploadUserImage(image: Upload!): Boolean!
}

Limitations

The default Upload scalar is a write-only scalar that supports only accessing the value that was passed through the variables. It is not possible to use it as return value for a GraphQL field or set its value in a GraphQL Query:

type User {
    "This field will fail with ValueError"
    image: Upload
}

mutation {
    uploadUserImage(image: "data:text/plain;base64,QXJpYWRuZSByb2NrcyE=")
}

You are not required to use the Upload scalar implementation provided by Ariadne. You can implement your own if you wish to, so you can (for example) support file literals as base64 data.

Implementation differences

The Python value returned by the Upload scalar is not standardized and depends on your technology stack:

ariadne.asgi

Ariadne's ASGI support is based on Starlette and hence uploaded files are instances of UploadFile.

ariadne.wsgi

Ariadne's WSGI support uses the cgi module from Python's standard library that represents uploaded files as instances of FieldStorage.

Data in FieldStorage is not guaranteed to represent an uploaded file.

ariadne.contrib.django

Ariadne's Django integration uses request.FILES to obtain uploaded files. Depending on file uploads configuration in your Django project, the files are instances of UploadedFile or one of its subclasses.