Django Storages S3
Senior Django specialist for production-grade file storage on AWS S3 via django-storages and boto3 — public and private media, static files, presigned URLs, and CloudFront.
When to Use This Skill
- Serving static and/or media files from AWS S3 instead of the local filesystem
- Configuring the Django 4.2+
STORAGES dict or legacy DEFAULT_FILE_STORAGE
- Separating public (CDN-served) and private (presigned) file backends
- Generating presigned download or direct browser-to-S3 upload URLs
- Fronting S3 with CloudFront and writing a least-privilege IAM policy
- Migrating local
FileField/ImageField storage to S3 without code changes
- Testing storage code without hitting S3
Core Workflow
- Install & register —
pip install django-storages[s3] boto3; add "storages" to INSTALLED_APPS
- Configure credentials — Load from env vars or rely on an attached IAM role; never hardcode
- Wire the
STORAGES dict — Set default (media) and staticfiles backends with separate location prefixes
- Add named backends — Split public vs. private buckets/ACLs as additional
STORAGES entries when needed
- Verify & test — Run
collectstatic, confirm uploads land in S3, and mock S3 in tests with InMemoryStorage or moto
Reference Guide
Load detailed guidance based on context:
| Topic |
Reference |
Load When |
| Settings & STORAGES |
references/configuration.md |
Core settings, 4.2+ vs legacy, CloudFront |
| Custom backends |
references/custom-backends.md |
Public vs. private buckets, per-field storage |
| Presigned URLs |
references/presigned-urls.md |
Download links, direct browser uploads |
| Testing & IAM |
references/testing-storages.md |
Mocking S3, IAM policy, common pitfalls |
Minimal Working Example
The snippet below demonstrates the core MUST DO constraints: env-loaded credentials, STORAGES dict, separate media/static locations, and default_acl=None on the media backend.
# settings.py
import os
AWS_STORAGE_BUCKET_NAME = os.environ["AWS_STORAGE_BUCKET_NAME"]
AWS_S3_REGION_NAME = os.environ.get("AWS_S3_REGION_NAME", "us-east-1")
AWS_S3_CUSTOM_DOMAIN = f"{AWS_STORAGE_BUCKET_NAME}.s3.{AWS_S3_REGION_NAME}.amazonaws.com"
# On EC2/ECS/Lambda, omit keys entirely — boto3 uses the attached IAM role.
STORAGES = {
"default": { # media uploads
"BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
"OPTIONS": {
"bucket_name": AWS_STORAGE_BUCKET_NAME,
"location": "media",
"default_acl": None, # rely on bucket policy, not per-object ACLs
"file_overwrite": False,
"querystring_auth": False, # public objects → clean URLs
},
},
"staticfiles": {
"BACKEND": "storages.backends.s3boto3.S3StaticStorage",
"OPTIONS": {
"bucket_name": AWS_STORAGE_BUCKET_NAME,
"location": "static",
},
},
}
MEDIA_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/media/"
STATIC_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/static/"
# models.py — uploads go straight to S3 on save()
from django.db import models
class Document(models.Model):
file = models.FileField(upload_to="docs/") # uses STORAGES["default"]
Auditing an Existing Configuration
When reviewing a project that already uses S3 (not greenfield), walk this
checklist — each item is a constraint below rephrased as "find X, confirm Y":
- Credentials —
grep -rn "AWS_SECRET_ACCESS_KEY\|aws_secret" settings/ → confirm values come from os.environ/django-environ or an IAM role, never literals committed to the repo.
- ACLs —
grep -rn "default_acl\|AWS_DEFAULT_ACL" . → on buckets created after April 2023, every value must be None. Any "public-read"/"private" will raise AccessControlListNotSupported; public access belongs in a bucket policy.
- Storage backend — confirm Django 4.2+ uses the
STORAGES dict, not DEFAULT_FILE_STORAGE/STATICFILES_STORAGE (removed in Django 5.1, so silently ignored on 5.1/5.2/6.0); confirm the static class is S3StaticStorage, not a fabricated name.
- Locations — confirm
default (media) and staticfiles have distinct location prefixes or buckets so collectstatic never collides with uploads.
- Region — confirm
region_name (or the global AWS_S3_REGION_NAME) matches the bucket's real region and that AWS_S3_CUSTOM_DOMAIN includes the region segment for non-us-east-1 buckets.
- Presigning — for private backends, confirm
querystring_auth=True and custom_domain=None; confirm presigned .url() results aren't cached past AWS_QUERYSTRING_EXPIRE.
- Overwrite cleanup — where
file_overwrite=False, confirm replaced files are explicitly deleted (otherwise superseded objects leak).
- IAM — confirm the policy grants only
Get/Put/Delete/ListBucket on the bucket ARN, not broader S3 access.
Constraints
MUST DO
- Load AWS credentials from environment variables or an attached IAM role
- Set
default_acl=None so bucket policies (not object ACLs) control access
- Give static and media files separate
location prefixes or separate buckets
- Use the
STORAGES dict on Django 4.2+ (same config through 5.2 LTS and 6.0); DEFAULT_FILE_STORAGE/STATICFILES_STORAGE were removed in 5.1, so reserve them for < 4.2 only
- Set
custom_domain=None on any backend that issues presigned URLs
- Mock S3 (
InMemoryStorage or moto) in tests instead of hitting real buckets
MUST NOT DO
- Hardcode
AWS_SECRET_ACCESS_KEY in settings.py or commit it
- Mix
querystring_auth=True with a custom_domain (presigning breaks)
- Mix static and media files under the same prefix
- Grant the IAM user broader than
Get/Put/Delete/ListBucket on the bucket ARN
- Rely on per-object ACLs on buckets created after April 2023 (ACLs disabled by default)
Knowledge Reference
django-storages, S3Boto3Storage, S3StaticStorage, boto3, STORAGES dict, presigned URLs, generate_presigned_post, CloudFront, IAM policy, InMemoryStorage, moto
Related Skills
django-expert — core Django models, DRF, and ORM that produce the files this skill persists to S3
fullstack-guardian — secure end-to-end upload flows and access control around stored files
devops-engineer — provisioning the S3 buckets, IAM roles, and CloudFront distributions this skill targets
Documentation
1---2name: django-storages-s33description: "Use when configuring Django to store static and media files on AWS S3 with django-storages. Invoke when working with the STORAGES setting, S3 buckets, presigned URLs, CloudFront, or boto3-backed file storage in settings.py. Configures the Django 4.2+ STORAGES dict, public/private custom backends, presigned GET/POST URLs, IAM policies, and S3 mocking for tests. Trigger terms: django-storages, S3, boto3, S3Boto3Storage, STORAGES, presigned URL, CloudFront, media files, collectstatic, AWS_STORAGE_BUCKET_NAME."4license: MIT5compatibility: opencode6metadata:7 source: https://skillmd.com/skills/farmage/django-storages-s38 author: https://github.com/awais7869 version: "1.0.0"10 domain: backend11 triggers: django-storages, S3, boto3, S3Boto3Storage, STORAGES, presigned URL, CloudFront, media files, collectstatic12 role: specialist13 scope: implementation14 output-format: code15 related-skills: django-expert16---1718# Django Storages S31920Senior Django specialist for production-grade file storage on AWS S3 via `django-storages` and `boto3` — public and private media, static files, presigned URLs, and CloudFront.2122## When to Use This Skill2324- Serving static and/or media files from AWS S3 instead of the local filesystem25- Configuring the Django 4.2+ `STORAGES` dict or legacy `DEFAULT_FILE_STORAGE`26- Separating public (CDN-served) and private (presigned) file backends27- Generating presigned download or direct browser-to-S3 upload URLs28- Fronting S3 with CloudFront and writing a least-privilege IAM policy29- Migrating local `FileField`/`ImageField` storage to S3 without code changes30- Testing storage code without hitting S33132## Core Workflow33341. **Install & register** — `pip install django-storages[s3] boto3`; add `"storages"` to `INSTALLED_APPS`352. **Configure credentials** — Load from env vars or rely on an attached IAM role; never hardcode363. **Wire the `STORAGES` dict** — Set `default` (media) and `staticfiles` backends with separate `location` prefixes374. **Add named backends** — Split public vs. private buckets/ACLs as additional `STORAGES` entries when needed385. **Verify & test** — Run `collectstatic`, confirm uploads land in S3, and mock S3 in tests with `InMemoryStorage` or `moto`3940## Reference Guide4142Load detailed guidance based on context:4344| Topic | Reference | Load When |45|-------|-----------|-----------|46| Settings & STORAGES | `references/configuration.md` | Core settings, 4.2+ vs legacy, CloudFront |47| Custom backends | `references/custom-backends.md` | Public vs. private buckets, per-field storage |48| Presigned URLs | `references/presigned-urls.md` | Download links, direct browser uploads |49| Testing & IAM | `references/testing-storages.md` | Mocking S3, IAM policy, common pitfalls |5051## Minimal Working Example5253The snippet below demonstrates the core MUST DO constraints: env-loaded credentials, `STORAGES` dict, separate media/static locations, and `default_acl=None` on the media backend.5455```python56# settings.py57import os5859AWS_STORAGE_BUCKET_NAME = os.environ["AWS_STORAGE_BUCKET_NAME"]60AWS_S3_REGION_NAME = os.environ.get("AWS_S3_REGION_NAME", "us-east-1")61AWS_S3_CUSTOM_DOMAIN = f"{AWS_STORAGE_BUCKET_NAME}.s3.{AWS_S3_REGION_NAME}.amazonaws.com"62# On EC2/ECS/Lambda, omit keys entirely — boto3 uses the attached IAM role.6364STORAGES = {65 "default": { # media uploads66 "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",67 "OPTIONS": {68 "bucket_name": AWS_STORAGE_BUCKET_NAME,69 "location": "media",70 "default_acl": None, # rely on bucket policy, not per-object ACLs71 "file_overwrite": False,72 "querystring_auth": False, # public objects → clean URLs73 },74 },75 "staticfiles": {76 "BACKEND": "storages.backends.s3boto3.S3StaticStorage",77 "OPTIONS": {78 "bucket_name": AWS_STORAGE_BUCKET_NAME,79 "location": "static",80 },81 },82}8384MEDIA_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/media/"85STATIC_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/static/"86```8788```python89# models.py — uploads go straight to S3 on save()90from django.db import models9192class Document(models.Model):93 file = models.FileField(upload_to="docs/") # uses STORAGES["default"]94```9596## Auditing an Existing Configuration9798When reviewing a project that already uses S3 (not greenfield), walk this99checklist — each item is a constraint below rephrased as "find X, confirm Y":1001011. **Credentials** — `grep -rn "AWS_SECRET_ACCESS_KEY\|aws_secret" settings/` → confirm values come from `os.environ`/`django-environ` or an IAM role, never literals committed to the repo.1022. **ACLs** — `grep -rn "default_acl\|AWS_DEFAULT_ACL" .` → on buckets created after April 2023, every value must be `None`. Any `"public-read"`/`"private"` will raise `AccessControlListNotSupported`; public access belongs in a bucket policy.1033. **Storage backend** — confirm Django 4.2+ uses the `STORAGES` dict, not `DEFAULT_FILE_STORAGE`/`STATICFILES_STORAGE` (removed in Django 5.1, so silently ignored on 5.1/5.2/6.0); confirm the static class is `S3StaticStorage`, not a fabricated name.1044. **Locations** — confirm `default` (media) and `staticfiles` have distinct `location` prefixes or buckets so `collectstatic` never collides with uploads.1055. **Region** — confirm `region_name` (or the global `AWS_S3_REGION_NAME`) matches the bucket's real region and that `AWS_S3_CUSTOM_DOMAIN` includes the region segment for non-`us-east-1` buckets.1066. **Presigning** — for private backends, confirm `querystring_auth=True` **and** `custom_domain=None`; confirm presigned `.url()` results aren't cached past `AWS_QUERYSTRING_EXPIRE`.1077. **Overwrite cleanup** — where `file_overwrite=False`, confirm replaced files are explicitly deleted (otherwise superseded objects leak).1088. **IAM** — confirm the policy grants only `Get/Put/Delete/ListBucket` on the bucket ARN, not broader S3 access.109110## Constraints111112### MUST DO113- Load AWS credentials from environment variables or an attached IAM role114- Set `default_acl=None` so bucket policies (not object ACLs) control access115- Give static and media files separate `location` prefixes or separate buckets116- Use the `STORAGES` dict on Django 4.2+ (same config through 5.2 LTS and 6.0); `DEFAULT_FILE_STORAGE`/`STATICFILES_STORAGE` were removed in 5.1, so reserve them for < 4.2 only117- Set `custom_domain=None` on any backend that issues presigned URLs118- Mock S3 (`InMemoryStorage` or `moto`) in tests instead of hitting real buckets119120### MUST NOT DO121- Hardcode `AWS_SECRET_ACCESS_KEY` in `settings.py` or commit it122- Mix `querystring_auth=True` with a `custom_domain` (presigning breaks)123- Mix static and media files under the same prefix124- Grant the IAM user broader than `Get/Put/Delete/ListBucket` on the bucket ARN125- Rely on per-object ACLs on buckets created after April 2023 (ACLs disabled by default)126127## Knowledge Reference128129django-storages, S3Boto3Storage, S3StaticStorage, boto3, STORAGES dict, presigned URLs, generate_presigned_post, CloudFront, IAM policy, InMemoryStorage, moto130131## Related Skills132133- `django-expert` — core Django models, DRF, and ORM that produce the files this skill persists to S3134- `fullstack-guardian` — secure end-to-end upload flows and access control around stored files135- `devops-engineer` — provisioning the S3 buckets, IAM roles, and CloudFront distributions this skill targets136137[Documentation](https://jeffallan.github.io/claude-skills/skills/backend/django-storages-s3/)