Upload Files in Django Directly to S3 in Production (2026)

Uploading files directly to S3 in Django for production environments bypasses your Django application server entirely for the file transfer, significantly improving performance and scalability.

Here’s a Django application handling user avatars, configured to upload directly to an S3 bucket:

# settings.py

AWS_ACCESS_KEY_ID = 'YOUR_ACCESS_KEY_ID'
AWS_SECRET_ACCESS_KEY = 'YOUR_SECRET_ACCESS_KEY'
AWS_STORAGE_BUCKET_NAME = 'your-django-bucket-name'
AWS_S3_CUSTOM_DOMAIN = f'{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com'
AWS_S3_OBJECT_URL_FOR_PUBLIC_ACCESS = True
AWS_DEFAULT_ACL = 'public-read' # Or 'private' if you use signed URLs

DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'
AWS_S3_REGION_NAME = 'us-east-1'

# If you need to specify a signature version
# AWS_S3_SIGNATURE_VERSION = 's3v4'

# Optional: If you're using a CDN in front of S3
# AWS_S3_CUSTOM_DOMAIN = 'cdn.yourdomain.com'

# models.py
from django.db import models
from django.core.files.storage import FileSystemStorage
from storages.backends.s3boto3 import S3Boto3Storage

class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    avatar = models.ImageField(storage=S3Boto3Storage(), blank=True, null=True)
    # ... other fields

# views.py
from django.shortcuts import render, redirect
from .models import UserProfile
from .forms import UserProfileForm

def upload_avatar(request, user_profile_id):
    profile = UserProfile.objects.get(id=user_profile_id)
    if request.method == 'POST':
        form = UserProfileForm(request.POST, request.FILES, instance=profile)
        if form.is_valid():
            form.save()
            return redirect('profile_detail', user_profile_id=user_profile_id)
    else:
        form = UserProfileForm(instance=profile)
    return render(request, 'upload_avatar.html', {'form': form})

# forms.py
from django import forms
from .models import UserProfile

class UserProfileForm(forms.ModelForm):
    class Meta:
        model = UserProfile
        fields = ['avatar'] # Only include fields you want to edit

This setup uses the django-storages library with the boto3 backend to interface with AWS S3. When a file is uploaded via a Django form, django-storages intercepts the ImageField (or any FileField) and, based on the DEFAULT_FILE_STORAGE setting, directs the upload operation to S3 instead of the local filesystem.

The core problem this solves is the bottleneck of your Django server handling file uploads. In a typical setup, a POST request with a file would be processed by Django, which then reads the file from the request and writes it to the server’s disk. If you have many users uploading many files concurrently, your web server’s disk I/O and CPU can become saturated. By uploading directly to S3, the user’s browser establishes a direct connection with S3, offloading the entire file transfer from your Django application. This means your Django server is only responsible for handling the HTTP request and updating the database with the file’s S3 URL, a trivial operation.

Internally, when you set DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage', Django’s file handling mechanisms are redirected. Instead of using django.core.files.storage.FileSystemStorage, it uses the S3 backend. When you call form.save(), the ImageField’s save() method is invoked. This method, in turn, calls the configured storage backend’s save() method. The S3Boto3Storage backend then uses boto3 to stream the uploaded file directly to your specified S3 bucket.

The primary levers you control are:

• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: Your AWS credentials. Never hardcode these in production. Use environment variables or AWS IAM roles for EC2 instances.
• AWS_STORAGE_BUCKET_NAME: The name of your S3 bucket. This must be globally unique.
• AWS_S3_REGION_NAME: The AWS region where your bucket resides (e.g., us-west-2, eu-central-1).
• DEFAULT_FILE_STORAGE: This is the master switch that tells Django to use S3 for all file operations by default.
• AWS_DEFAULT_ACL: Controls the default Access Control List for uploaded objects. public-read makes files directly accessible via their S3 URL. private requires signed URLs, which Django can generate or django-storages can help with.
• AWS_S3_CUSTOM_DOMAIN: Useful if you’re using a CDN or want to serve files from a custom subdomain (e.g., media.yourdomain.com).

The most surprising part about setting up direct S3 uploads is how little Django code you actually need to change. Beyond the settings.py configuration and ensuring your ImageField or FileField is correctly defined, the rest of your Django views and models can largely remain the same. The django-storages library acts as a near-drop-in replacement for the default file storage, abstracting away the S3 interaction. This means your existing form.save() calls will automatically start writing to S3 without requiring manual S3 API calls within your views.

The next conceptual step is managing file access policies, specifically when to use public URLs versus generating pre-signed URLs for private files.