Registry / aws / django-s3-storage

django-s3-storage

library0.15.0pypypi✓ verified 87d ago

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.

aws web-framework database

pip install django-s3-storage

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-S3-STORAGE

django-s3-storage

awspythonv0.15.0

Install

5.6s avg

Import

935ms

Disk

99MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.15.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.954s · 99.4MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.6s · import 0.916s · 100MB

99MB installed

● package 99MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

S3Storage

✓ from django_s3_storage.storage import S3Storage

✗ from django_s3_storage import S3Storage

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

ManifestStaticS3Storage

✓ from django_s3_storage.storage import ManifestStaticS3Storage

✗ from django_s3_storage import ManifestStaticS3Storage

Also in storage submodule, not top-level.

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'

Debug

Known issues

breakingIn 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.

affects: >=0.14.0

deprecatedDjango'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'}}

affects: all

gotchaMisconfiguration 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.

affects: all

gotchaThe 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.

affects: all

gotchaIf 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.

affects: all

Errors

Common errors & fixes

The 'django_s3_storage' package is not installed.

Missing dependency or incorrect Python environment.

fix

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

ModuleNotFoundError: No module named 'django_s3_storage'

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

fix

Install the package: pip install django-s3-storage

botocore.exceptions.NoCredentialsError: Unable to locate credentials

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.

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

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.

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

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.

Upgrade

Version history

0.15.0latest on PyPI · released Nov 4, 2023

Audit

Dependencies

djangorequiredCore dependency; requires Django >= 3.2

boto3requiredRequired for S3 interaction

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/etianen/django-s3-storage ↗

packagehttps://pypi.org/project/django-s3-storage/ ↗