Install & Compatibility
Where this runs
tested against v1.14.6 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Boto3Storage
✓ from storages.backends.s3boto3 import S3Boto3Storage
✗ from storages.backends.s3boto3 import S3Boto3Storage
To quickly set up `django-storages`, add 'storages' to your `INSTALLED_APPS` and configure `DEFAULT_FILE_STORAGE` to point to your chosen backend. Provide the necessary credentials and bucket names, typically sourced from environment variables for security. This example demonstrates Amazon S3 configuration.
# In your Django project's settings.py
INSTALLED_APPS = [
# ... your other apps
'storages',
]
# --- Example for Amazon S3 Backend ---
# Make sure to install boto3: pip install boto3
# Set DEFAULT_FILE_STORAGE for media files
DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'
# Your AWS settings
AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID', '')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY', '')
AWS_STORAGE_BUCKET_NAME = os.environ.get('AWS_STORAGE_BUCKET_NAME', '')
AWS_S3_REGION_NAME = os.environ.get('AWS_S3_REGION_NAME', 'us-east-1') # e.g., 'us-east-1'
# Optional: Set a custom domain for your media files if using a CDN
# AWS_S3_CUSTOM_DOMAIN = 'your-cdn-domain.com'
# Optional: Control file access. 'public-read' makes files publicly accessible.
# AWS_DEFAULT_ACL = 'public-read'
# Optional: Don't sign URLs by default (often useful for public access)
# AWS_QUERYSTRING_AUTH = False
# --- Example for Google Cloud Storage Backend (Optional) ---
# Make sure to install google-cloud-storage: pip install google-cloud-storage
# For GCS, you typically provide a path to a service account JSON key file
# or rely on application default credentials.
# GOOGLE_CLOUD_STORAGE_BUCKET_NAME = os.environ.get('GCS_BUCKET_NAME', '')
# GOOGLE_CLOUD_STORAGE_JSON_KEY_FILE = os.environ.get('GCS_JSON_KEY_FILE', '/path/to/your/key.json')
Debug
Known issues
gotchaForgetting to install the specific Python library for your chosen backend (e.g., `boto3` for S3, `google-cloud-storage` for GCS, `azure-storage-blob` for Azure) will result in `ModuleNotFoundError` or similar import errors when Django tries to initialize the storage backend.fixEnsure you install the correct backend dependency: `pip install django-storages[s3]` or `pip install boto3` (etc.) for the specific backend you are using.
affects: All versions
breakingVersions 1.12+ (including 1.14.x) of `django-storages` require Python 3.7+ and Django 3.2+. Older Python or Django versions are no longer supported and will lead to installation or runtime errors.fixUpgrade your Python environment to 3.7+ and your Django project to 3.2+ before upgrading `django-storages`. Consult the `django-storages` changelog for specific version compatibility details.
affects: >=1.12
gotchaIncorrect AWS IAM permissions or S3 bucket policy can lead to 'Access Denied' errors. Also, a mismatch between `AWS_S3_REGION_NAME` in your settings and the actual region of your S3 bucket is a common pitfall.fixVerify that your AWS user's IAM policy grants the necessary permissions (e.g., `s3:PutObject`, `s3:GetObject`, `s3:ListBucket`) to the specified bucket. Double-check that `AWS_S3_REGION_NAME` accurately reflects your bucket's region.
affects: All versions using S3
gotchaMisconfiguration of `AWS_DEFAULT_ACL` or `AWS_QUERYSTRING_AUTH` can lead to files being unexpectedly public/private, or URLs that expire too quickly. For example, if `AWS_QUERYSTRING_AUTH` is `True` (default), all URLs will be signed and time-limited, which might not be desired for publicly accessible static assets.fixExplicitly set `AWS_DEFAULT_ACL = 'public-read'` for publicly accessible files. Set `AWS_QUERYSTRING_AUTH = False` if you want non-signed, non-expiring URLs for your files (e.g., static files served directly from S3).
affects: All versions using S3
gotchaA `NameError: name 'os' is not defined` indicates that the `os` module was used without being imported. This typically happens when trying to access environment variables (e.g., `os.environ.get`) without `import os` at the top of the file.fixEnsure `import os` is present at the beginning of any Python file where `os` functions (like `os.environ.get`) are used.
affects: All versions
gotchaA `NameError` for an unimported module (e.g., `os`) will prevent script execution before `django-storages` functionality can be initialized or used. This error typically signifies a basic Python coding oversight in the script attempting to interact with the library.fixEnsure all necessary Python modules, such as `os`, are explicitly imported at the beginning of your script before their functions or attributes are accessed (e.g., `import os`).
affects: All versions (related to general Python script logic, not specific library versions)
Upgrade
Version history
1.14.6latest on PyPI · released Apr 2, 2025
Audit
Dependencies
boto3optionalRequired for Amazon S3 backend.
google-cloud-storageoptionalRequired for Google Cloud Storage backend.
azure-storage-bloboptionalRequired for Azure Blob Storage backend.