django-storages-s3

S3 storage backend for Django.

This project is based on django-storages but focuses exclusively on Amazon S3 and S3-compatible storage services (e.g. RustFS, Cloudflare R2, DigitalOcean Spaces). By removing support for other storage backends, it aims to be a leaner, more focused package for projects that only need S3.

Requirements

• Python >= 3.12
• Django >= 5.2
• boto3 >= 1.42

Installation

pip install django-storages-s3

Usage

To save media files to S3:

STORAGES = {
    "default": {
        "BACKEND": "storages.s3.S3Storage",
        "OPTIONS": {
            "bucket_name": "my-media-bucket",
            "region_name": "us-east-1",
        },
    },
}

To put static files on S3 via collectstatic:

STORAGES = {
    "staticfiles": {
        "BACKEND": "storages.s3.S3StaticStorage",
        "OPTIONS": {
            "bucket_name": "my-static-bucket",
        },
    },
}

Settings can be provided per-backend via OPTIONS or globally via Django settings (e.g. AWS_STORAGE_BUCKET_NAME). Per-backend options take precedence.

Storage backends

• storages.s3.S3Storage - General file storage
• storages.s3.S3StaticStorage - Static files (querystring auth disabled)
• storages.s3.S3ManifestStaticStorage - Static files with Django's ManifestFilesMixin

Authentication

There are several methods for specifying AWS credentials. S3Storage searches for them in this order:

1. session_profile / AWS_S3_SESSION_PROFILE
2. access_key / AWS_S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID
3. secret_key / AWS_S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY
4. security_token / AWS_SESSION_TOKEN or AWS_SECURITY_TOKEN
5. Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
6. Boto3's default session (instance profile, config files, etc.)

Settings

All settings can be provided as OPTIONS keys (for per-backend configuration) or as global Django settings.

Bucket and storage

URLs

When public_domain is set, url() uses it for external URLs while storage operations continue to use endpoint_url.

Connection

Compression

Other

IAM Policy

Minimum IAM policy for common usage:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObjectAcl",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::example-bucket-name/*",
                "arn:aws:s3:::example-bucket-name"
            ]
        }
    ]
}

For more information about Principal, see AWS JSON Policy Elements.

License

BSD 3-Clause. See LICENSE for details.