Introduction

The error Could not load Amazon S3 bindings occurs when using django-storages with the S3 backend but the required AWS SDK packages are not installed or are incorrectly configured. django-storages provides a storage backend that lets Django store files (media, static) in Amazon S3, but it depends on either boto3 or the older boto library to communicate with AWS.

The Error

The full error message is typically:

ImproperlyConfigured: Could not load Amazon S3 bindings.
See https://github.com/jschneier/django-storages

Or in newer versions:

ModuleNotFoundError: No module named 'boto3'

Why This Happens

django-storages does not install boto3 automatically — it is listed as an optional dependency. You must install it separately. The required packages are:

• boto3: The official Amazon Web Services SDK for Python, providing high-level APIs for S3 and other services
• botocore: The low-level AWS interface used internally by boto3 (installed automatically with boto3)

How to Fix It

Step 1: Install boto3

pip install boto3

Or install django-storages with the S3 extras:

pip install django-storages[s3]

This installs both django-storages and boto3 together.

Step 2: Configure Django Settings

1# settings.py
2
3INSTALLED_APPS = [
4    # ...
5    'storages',
6]
7
8# S3 Configuration
9AWS_ACCESS_KEY_ID = 'your-access-key-id'
10AWS_SECRET_ACCESS_KEY = 'your-secret-access-key'
11AWS_STORAGE_BUCKET_NAME = 'your-bucket-name'
12AWS_S3_REGION_NAME = 'us-east-1'
13
14# Optional settings
15AWS_S3_CUSTOM_DOMAIN = f'{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com'
16AWS_DEFAULT_ACL = None  # Use bucket's default ACL
17AWS_S3_OBJECT_PARAMETERS = {
18    'CacheControl': 'max-age=86400',
19}
20
21# Use S3 for static and media files
22STATICFILES_STORAGE = 'storages.backends.s3boto3.S3StaticStorage'
23DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

Step 3: Verify the Installation

python -c "import boto3; print(boto3.__version__)"
python -c "from storages.backends.s3boto3 import S3Boto3Storage; print('OK')"

Django 4.2+ / django-storages 1.14+

In newer versions, the storage configuration uses the STORAGES setting:

1# settings.py (Django 4.2+)
2
3STORAGES = {
4    "default": {
5        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
6        "OPTIONS": {
7            "bucket_name": "my-media-bucket",
8            "region_name": "us-east-1",
9        },
10    },
11    "staticfiles": {
12        "BACKEND": "storages.backends.s3boto3.S3StaticStorage",
13        "OPTIONS": {
14            "bucket_name": "my-static-bucket",
15        },
16    },
17}

Using Environment Variables (Recommended)

Never hardcode AWS credentials. Use environment variables:

1import os
2
3AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID')
4AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY')
5AWS_STORAGE_BUCKET_NAME = os.environ.get('AWS_STORAGE_BUCKET_NAME')

Or use IAM roles (preferred for EC2/ECS deployments):

1# When using IAM roles, do NOT set these:
2# AWS_ACCESS_KEY_ID = ...
3# AWS_SECRET_ACCESS_KEY = ...
4# boto3 will automatically use the instance's IAM role credentials

Old boto vs boto3

If you are upgrading from an older django-storages version, note the backend class changed:

1# Old (boto — deprecated)
2DEFAULT_FILE_STORAGE = 'storages.backends.s3boto.S3BotoStorage'
3# pip install boto  (no longer maintained)
4
5# New (boto3 — current)
6DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'
7# pip install boto3

If you see Could not load Amazon S3 bindings and have boto (not boto3) installed, you are likely using the old backend class. Switch to s3boto3.

Testing S3 Integration

Verify everything works with the Django shell:

1python manage.py shell
2
3from django.core.files.storage import default_storage
4from django.core.files.base import ContentFile
5
6# Upload a test file
7path = default_storage.save('test/hello.txt', ContentFile(b'Hello S3!'))
8print(f"Saved to: {path}")
9
10# Read it back
11with default_storage.open(path) as f:
12    print(f.read())
13
14# Delete it
15default_storage.delete(path)

Common Pitfalls

• boto vs boto3: The old boto package is deprecated and no longer maintained. Always use boto3 with the s3boto3 backend. If you have boto installed but not boto3, the new backend will not work.
• Virtual environment mismatch: If boto3 is installed globally but your Django project runs in a virtual environment (or vice versa), the import will fail. Always install inside your active environment.
• Requirements file: Add boto3 (or django-storages[s3]) to your requirements.txt to ensure it is installed during deployments.
• CORS configuration: If serving static files directly from S3 to browsers, configure CORS on your S3 bucket. Missing CORS rules cause font and AJAX loading failures.
• collectstatic slowness: Running python manage.py collectstatic with S3 storage can be slow due to network overhead. Use --no-input and consider the ManifestStaticFilesStorage for cache busting.

Summary

• Install boto3 alongside django-storages: pip install django-storages[s3]
• Use the s3boto3 backend (not the deprecated s3boto)
• Configure AWS credentials via environment variables or IAM roles, never hardcoded
• For Django 4.2+, use the new STORAGES dictionary setting
• Test with default_storage.save() in the Django shell to verify the setup