Skip to main content

A lightweight file uploader input for Django and Amazon S3

Project description

A lightweight file upload input for Django and Amazon S3.

Django-S3File allows you to upload files directly AWS S3 effectively bypassing your application server. This allows you to avoid long running requests from large file uploads. This is particularly helpful for if you run your service on AWS Lambda or Heroku where you have a hard request limit.

PyPi Version Test Coverage GitHub license


  • lightweight: less 200 lines
  • no JavaScript or Python dependencies (no jQuery)
  • easy integration
  • works just like the built-in
  • extendable JavaScript API

For the Nerds



Make sure you have Amazon S3 storage setup correctly.

Just install S3file using pip.

pip install django-s3file
# or
pipenv install django-s3file

Add the S3File app and middleware in your settings:




S3File automatically replaces Django’s ClearableFileInput widget, you do not need to alter your code at all.

The ClearableFileInput widget is only than automatically replaced when the DEFAULT_FILE_STORAGE setting is set to django-storagesS3Boto3Storage or the dummy FileSystemStorage is enabled.

Setting up the AWS S3 bucket

Upload folder

S3File uploads to a single folder. Files are later moved by Django when they are saved to the upload_to location.

It is recommended to setup expiration for that folder, to ensure that old and unused file uploads don’t add up and produce costs.

The default folder name is: tmp/s3file You can change it by changing the S3FILE_UPLOAD_PATH setting.

CORS policy

You will need to allow POST from all origins. Just add the following to your CORS policy.

    "AllowedHeaders": [
    "AllowedMethods": [
    "AllowedOrigins": [
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000

Progress Bar

S3File does emit progress signals that can be used to display some kind of progress bar. Signals named progress are emitted for both each individual file input as well as for the form as a whole.

The progress signal carries the following details:


    progress: 0.4725307607171312  // total upload progress of either a form or single input
    loaded: 1048576  // total upload progress of either a form or single input
    total: 2219064  // total bytes to upload
    currentFile: File {}  // file object
    currentFileName: "text.txt"  // file name of the file currently uploaded
    currentFileProgress: 0.47227834703299176  // upload progress of that file
    originalEvent: ProgressEvent {} // the original XHR onprogress event

The following example implements a Boostrap progress bar for upload progress of an entire form.

<div class="progress">
  <div class="progress-bar" role="progressbar" style="width: 0%;" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">0%</div>
(function () {
    var form = document.getElementsByTagName('form')[0]
    var progressBar = document.getElementsByClassName('progress-bar')[0]

    form.addEventListener('progress', function (event) {
        // event.detail.progress is a value between 0 and 1
        var percent = Math.round(event.detail.progress * 100)

        progressBar.setAttribute('style', 'width:' + percent + '%')
        progressBar.setAttribute('aria-valuenow', percent)
        progressBar.innerText = percent + '%'

Using S3File in development

Using S3File in development can be helpful especially if you want to use the progress signals described above. Therefore, S3File comes with a AWS S3 dummy backend. It behaves similar to the real S3 storage backend. It is automatically enabled, if the DEFAULT_FILE_STORAGE setting is set to FileSystemStorage.

To prevent users from accidentally using the FileSystemStorage and the insecure S3 dummy backend in production, there is also an additional deployment check that will error if you run Django’s deployment check suite:

python check --deploy

We recommend always running the deployment check suite as part of your deployment pipeline.

Uploading multiple files

Django does have limited support for uploading multiple files. S3File fully supports this feature. The custom middleware makes ensure that files are accessible via request.FILES, even though they have been uploaded to AWS S3 directly and not to your Django application server.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-s3file, version 5.3.0
Filename, size File type Python version Upload date Hashes
Filename, size django_s3file-5.3.0-py2.py3-none-any.whl (15.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size django-s3file-5.3.0.tar.gz (56.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page