django-s3-storage

0.15.0 verified Mon Apr 27 auth: no python

A Django storage backend for Amazon S3. It provides a drop-in replacement for Django’s default file storage, with support for custom domains, ACLs, and more. Current version: 0.15.0. Release cadence is irregular, with minor and patch releases as needed.

pip install django-s3-storage

Common errors

error The 'django_s3_storage' package is not installed. ↓

cause Missing dependency or incorrect Python environment.

fix

Run: pip install django-s3-storage[boto3]

error ModuleNotFoundError: No module named 'django_s3_storage' ↓

cause The library is not installed or not in the current Python path.

fix

Install the package: pip install django-s3-storage

error botocore.exceptions.NoCredentialsError: Unable to locate credentials ↓

cause AWS credentials are not set in environment variables or settings.

fix

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or configure via AWS CLI.

error django.core.exceptions.ImproperlyConfigured: Requested setting DEFAULT_FILE_STORAGE, but settings are not configured. ↓

cause The storage backend setting is referenced before Django settings are fully loaded.

fix

Ensure DEFAULT_FILE_STORAGE is defined in settings.py, not in a module-level variable that is evaluated early.

error botocore.exceptions.ClientError: An error occurred (NoSuchBucket) when calling the PutObject operation: The specified bucket does not exist ↓

cause The S3 bucket specified in AWS_S3_BUCKET_NAME does not exist.

fix

Create the bucket in AWS S3 console or via AWS CLI, then verify the bucket name is correct.

Warnings

breaking In version 0.14.0, the default value for AWS_S3_BUCKET_AUTH changed from True to False. If you relied on the old default (signed URLs), you must explicitly set AWS_S3_BUCKET_AUTH = True. ↓

fix Set AWS_S3_BUCKET_AUTH = True in settings if you need signed URLs.

deprecated Django's DEFAULT_FILE_STORAGE and STATICFILES_STORAGE settings are deprecated in Django 4.2+ in favor of STORAGES. ↓

fix Use the STORAGES dict instead: STORAGES = {'default': {'BACKEND': 'django_s3_storage.storage.S3Storage'}, 'staticfiles': {'BACKEND': 'django_s3_storage.storage.ManifestStaticS3Storage'}}

gotcha Misconfiguration of AWS_S3_BUCKET_AUTH can cause public files to be inaccessible or private files to be exposed. The setting controls whether file URLs are signed. When False, files are publicly readable (bucket policy required). When True, URLs are signed with AWS credentials. ↓

fix Ensure AWS_S3_BUCKET_AUTH matches your bucket's public/private access policy.

gotcha The library does not automatically create the S3 bucket. You must create the bucket manually or via another tool, or the storage backend will fail with a 404 error on first usage. ↓

fix Create the S3 bucket before running Django collectstatic or saving files.

gotcha If you use a custom domain (e.g., via AWS_S3_CUSTOM_DOMAIN), ensure that the endpoint region matches. Misconfiguration can lead to SignatureDoesNotMatch errors. ↓

fix Set AWS_S3_CUSTOM_DOMAIN to your CDN or S3 bucket's custom domain, and verify AWS_REGION is correct.

Install

pip install django-s3-storage[boto3]

Imports

S3Storage

wrong

from django_s3_storage import S3Storage

correct

from django_s3_storage.storage import S3Storage

S3Storage is in the storage submodule, not at the package root.

ManifestStaticS3Storage

wrong

from django_s3_storage import ManifestStaticS3Storage

correct

from django_s3_storage.storage import ManifestStaticS3Storage

Also in storage submodule, not top-level.

Quickstart

Minimal configuration for S3 file and static storage.

import os

# settings.py
INSTALLED_APPS = [
    'django_s3_storage',
    ...
]

AWS_REGION = 'us-east-1'
AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID', '')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY', '')
AWS_S3_BUCKET_NAME = 'my-bucket'
AWS_S3_BUCKET_AUTH = False

DEFAULT_FILE_STORAGE = 'django_s3_storage.storage.S3Storage'
STATICFILES_STORAGE = 'django_s3_storage.storage.ManifestStaticS3Storage'