{"id":13617282,"url":"https://github.com/etianen/django-s3-storage","last_synced_at":"2025-04-11T19:14:19.577Z","repository":{"id":25865681,"uuid":"29305621","full_name":"etianen/django-s3-storage","owner":"etianen","description":"Django Amazon S3 file storage.","archived":false,"fork":false,"pushed_at":"2024-09-08T11:49:35.000Z","size":227,"stargazers_count":423,"open_issues_count":5,"forks_count":93,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-11T19:14:12.136Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mageewp/Zippy","license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etianen.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-15T16:12:05.000Z","updated_at":"2025-03-24T00:02:26.000Z","dependencies_parsed_at":"2024-01-17T00:54:13.825Z","dependency_job_id":"1606d26f-e234-4577-a92a-0229fc3085cf","html_url":"https://github.com/etianen/django-s3-storage","commit_stats":{"total_commits":209,"total_committers":32,"mean_commits":6.53125,"dds":"0.34928229665071775","last_synced_commit":"18aaec62794964af56fbf1fd346f866c28e8d0d0"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fdjango-s3-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fdjango-s3-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fdjango-s3-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fdjango-s3-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etianen","download_url":"https://codeload.github.com/etianen/django-s3-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248465345,"owners_count":21108244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T20:01:39.479Z","updated_at":"2025-04-11T19:14:19.552Z","avatar_url":"https://github.com/etianen.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"django-s3-storage\n=================\n\n**django-s3-storage** provides a Django Amazon S3 file storage.\n\n\nFeatures\n--------\n\n- Django file storage for Amazon S3.\n- Django static file storage for Amazon S3.\n- Works in Python 3!\n\n\nInstallation\n------------\n\n1. Install using ``pip install django-s3-storage``.\n2. Add ``'django_s3_storage'`` to your ``INSTALLED_APPS`` setting.\n3. Set your ``DEFAULT_FILE_STORAGE`` setting to ``\"django_s3_storage.storage.S3Storage\"``.\n4. Set your ``STATICFILES_STORAGE`` setting to ``\"django_s3_storage.storage.StaticS3Storage\"`` or ``\"django_s3_storage.storage.ManifestStaticS3Storage\"``.\n5. Configure your Amazon S3 settings (see Available settings, below).\n\n\nAuthentication settings\n-----------------------\n\nUse the following settings to authenticate with Amazon AWS.\n\n.. code:: python\n\n    # The AWS region to connect to.\n    AWS_REGION = \"us-east-1\"\n\n    # The AWS access key to use.\n    AWS_ACCESS_KEY_ID = \"\"\n\n    # The AWS secret access key to use.\n    AWS_SECRET_ACCESS_KEY = \"\"\n\n    # The optional AWS session token to use.\n    AWS_SESSION_TOKEN = \"\"\n\n\nFile storage settings\n---------------------\n\nUse the following settings to configure the S3 file storage. You must provide at least ``AWS_S3_BUCKET_NAME``.\n\n.. code:: python\n\n    # The name of the bucket to store files in.\n    AWS_S3_BUCKET_NAME = \"\"\n\n    # How to construct S3 URLs (\"auto\", \"path\", \"virtual\").\n    AWS_S3_ADDRESSING_STYLE = \"auto\"\n\n    # The full URL to the S3 endpoint. Leave blank to use the default region URL.\n    AWS_S3_ENDPOINT_URL = \"\"\n\n    # A prefix to be applied to every stored file. This will be joined to every filename using the \"/\" separator.\n    AWS_S3_KEY_PREFIX = \"\"\n\n    # Whether to enable authentication for stored files. If True, then generated URLs will include an authentication\n    # token valid for `AWS_S3_MAX_AGE_SECONDS`. If False, then generated URLs will not include an authentication token,\n    # and their permissions will be set to \"public-read\".\n    AWS_S3_BUCKET_AUTH = True\n\n    # How long generated URLs are valid for. This affects the expiry of authentication tokens if `AWS_S3_BUCKET_AUTH`\n    # is True. It also affects the \"Cache-Control\" header of the files.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_MAX_AGE_SECONDS = 60 * 60  # 1 hours.\n\n    # A URL prefix to be used for generated URLs. This is useful if your bucket is served through a CDN.\n    AWS_S3_PUBLIC_URL = \"\"\n\n    # If True, then files will be stored with reduced redundancy. Check the S3 documentation and make sure you\n    # understand the consequences before enabling.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_REDUCED_REDUNDANCY = False\n\n    # The Content-Disposition header used when the file is downloaded. This can be a string, or a function taking a\n    # single `name` argument.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_CONTENT_DISPOSITION = \"\"\n\n    # The Content-Language header used when the file is downloaded. This can be a string, or a function taking a\n    # single `name` argument.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_CONTENT_LANGUAGE = \"\"\n\n    # A mapping of custom metadata for each file. Each value can be a string, or a function taking a\n    # single `name` argument.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_METADATA = {}\n\n    # If True, then files will be stored using AES256 server-side encryption.\n    # If this is a string value (e.g., \"aws:kms\"), that encryption type will be used.\n    # Otherwise, server-side encryption is not be enabled.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_ENCRYPT_KEY = False\n\n    # The AWS S3 KMS encryption key ID (the `SSEKMSKeyId` parameter) is set from this string if present.\n    # This is only relevant if AWS S3 KMS server-side encryption is enabled (above).\n    AWS_S3_KMS_ENCRYPTION_KEY_ID = \"\"\n\n    # If True, then text files will be stored using gzip content encoding. Files will only be gzipped if their\n    # compressed size is smaller than their uncompressed size.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_GZIP = True\n\n    # The signature version to use for S3 requests.\n    AWS_S3_SIGNATURE_VERSION = None\n\n    # If True, then files with the same name will overwrite each other. By default it's set to False to have\n    # extra characters appended.\n    AWS_S3_FILE_OVERWRITE = False\n\n    # If True, use default behaviour for boto3 of using threads when doing S3 operations.\n    # If gevent or similar is used it must be disabled due to interaction with boto3 causing time-outs.\n    AWS_S3_USE_THREADS = True\n\n    # Max pool of connections for massive S3 interactions\n    AWS_S3_MAX_POOL_CONNECTIONS = 10\n\n    # Time to raise timeout when submitting a new file\n    AWS_S3_CONNECT_TIMEOUT = 60\n\n**Important:** Several of these settings (noted above) will not affect existing files. To sync the new settings to\nexisting files, run ``./manage.py s3_sync_meta django.core.files.storage.default_storage``.\n\nThese settings can be provided in field storage definition like this:\n\n.. code:: python\n\n    from django.db import models\n\n    from django_s3_storage.storage import S3Storage\n\n    storage = S3Storage(aws_s3_bucket_name='test_bucket')\n\n\n    class Car(models.Model):\n        name = models.CharField(max_length=255)\n        photo = models.ImageField(storage=storage)\n\n**Note:** settings key in storage definition should be `lowercase`.\n\nStaticfiles storage settings\n----------------------------\n\nAll of the file storage settings are available for the staticfiles storage, suffixed with ``_STATIC``. You must provide\nat least ``AWS_S3_BUCKET_NAME_STATIC``. Remember to run ``./manage.py collectstatic`` after changing your staticfiles\nstorage backend.\n\nThe following staticfiles storage settings have different default values to their file storage counterparts.\n\n.. code:: python\n\n    AWS_S3_BUCKET_AUTH_STATIC = False\n\n\nThe following additional staticfiles storage settings also exist:\n\n.. code:: python\n\n    # For ManifestStaticS3Storage, how long the browser should cache md5-hashed filenames.  This affects the expiry of\n    # authentication tokens if `AWS_S3_BUCKET_AUTH` is True. It also affects the \"Cache-Control\" header of the files.\n    # Important: Changing this setting will not affect existing files.\n    AWS_S3_MAX_AGE_SECONDS_CACHED_STATIC = 60 * 60 * 24 * 365  # 1 year.\n\n\n**Important:** Several of these settings (noted above) will not affect existing files. To sync the new settings to\nexisting files, run ``./manage.py s3_sync_meta django.contrib.staticfiles.storage.staticfiles_storage``.\n\n\nOptimizing media file caching\n-----------------------------\n\nThe default settings assume that media file are private. This means that they are only accessible via S3 authenticated URLs, which is bad for browser caching.\n\nTo make media files public, and enable aggressive caching, make the following changes to your ``settings.py``.\n\n.. code:: python\n\n    AWS_S3_BUCKET_AUTH = False\n\n    AWS_S3_MAX_AGE_SECONDS = 60 * 60 * 24 * 365  # 1 year.\n\n**Important:** By making these changes, all media files will be public. Ensure they do not contain confidential information.\n\nThe default settings for staticfiles storage are already optimizing for aggressive caching.\n\n\nCustom URLs\n-----------\n\nSometimes the default settings aren't flexible enough and custom handling of object is needed. For\nexample, the ``Content-Disposition`` might be set to force download of a file instead of opening\nit:\n\n.. code:: python\n\n    url = storage.url(\"foo/bar.pdf\", extra_params={\"ResponseContentDisposition\": \"attachment\"})\n\nAnother example is a link to a specific version of the file (within a bucket that has versioning\nenabled):\n\n.. code:: python\n\n    url = storage.url(\"foo/bar.pdf\", extra_params={\"VersionId\": \"FRy3fTduRtqHsRAoNp0REzPJj_WunDfl\"})\n\nThe ``extra_params`` dict accepts the same parameters as `get_object() \u003chttps://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.get_object\u003e`_.\n\nPlease note, however, that **custom URLs will not work with AWS_S3_PUBLIC_URL** where the\nURL doesn't accept extra parameters, and it will raise ``ValueError``.\n\n\nPre-signed URL uploads\n----------------------\n\nPre-signed URLs allow temporary access to S3 objects without AWS credentials. A pre-signed URL allows HTTP clients to\nupload files directly, improving performance and reducing the load on your server.\n\nTo generate a presigned URL allowing a file upload with HTTP ``PUT``:\n\n.. code:: python\n\n    url = storage.url(\"foo/bar.pdf\", client_method=\"put_object\")\n\n\nManagement commands\n-------------------\n\n``s3_sync_meta``\n~~~~~~~~~~~~~~~~\n\nSyncronizes the meta information on S3 files.\n\nSeveral settings (noted above) will not affect existing files. Run this command to sync the new settings to existing files.\n\nExample usage: ``./manage.py s3_sync_meta django.core.files.storage.default_storage``\n\n\nIAM permissions\n---------------\n\nIn order to use all features of django-s3-storages, either authenticate with your AWS root credentials (not recommended), or create a dedicated IAM role. The minimum set of permissions required by django-s3-storage is:\n\n.. code::\n\n    {\n        \"Version\": \"2012-10-17\",\n        \"Statement\": [\n            {\n                \"Effect\": \"Allow\",\n                \"Action\": [\n                    \"s3:ListBucket\"\n                ],\n                \"Resource\": [\n                    \"arn:aws:s3:::my-bucket\"\n                ]\n            },\n            {\n                \"Effect\": \"Allow\",\n                \"Action\": [\n                    \"s3:PutObject\",\n                    \"s3:PutObjectAcl\",\n                    \"s3:GetObject\",\n                    \"s3:GetObjectAcl\",\n                    \"s3:DeleteObject\"\n                ],\n                \"Resource\": [\n                    \"arn:aws:s3:::my-bucket/*\"\n                ]\n            }\n        ]\n    }\n\n\nHow does django-s3-storage compare with django-storages?\n--------------------------------------------------------\n\n`django-storages \u003chttps://github.com/jschneier/django-storages\u003e`_ supports a variety of other storage backends,\nwhereas django-s3-storage provides similar features, but only supports S3. It was originally written to support\nPython 3 at a time when the future of django-storages was unclear. It's a small, well-tested and self-contained\nlibrary that aims to do one thing very well.\n\nThe author of django-s3-storage is not aware of significant differences in functionality with django-storages.\nIf you notice some differences, please file an issue!\n\n\nMigration from django-storages\n------------------------------\n\nIf your are updating a project that used `django-storages \u003chttps://pypi.python.org/pypi/django-storages\u003e`_ just for S3 file storage, migration is trivial.\n\nFollow the installation instructions, replacing 'storages' in ``INSTALLED_APPS``. Be sure to scrutinize the rest of your settings file for changes, most notably ``AWS_S3_BUCKET_NAME`` for ``AWS_STORAGE_BUCKET_NAME``.\n\n\nBuild status\n------------\n\nThis project is built on every push using the Travis-CI service.\n\n.. image:: https://travis-ci.org/etianen/django-s3-storage.svg?branch=master\n    :target: https://travis-ci.org/etianen/django-s3-storage\n\n\nSupport and announcements\n-------------------------\n\nDownloads and bug tracking can be found at the `main project\nwebsite \u003chttp://github.com/etianen/django-s3-storage\u003e`_.\n\n\nMore information\n----------------\n\nThe django-s3-storage project was developed by Dave Hall. You can get the code\nfrom the `django-s3-storage project site \u003chttp://github.com/etianen/django-s3-storage\u003e`_.\n\nDave Hall is a freelance web developer, based in Cambridge, UK. You can usually\nfind him on the Internet in a number of different places:\n\n-  `Website \u003chttp://www.etianen.com/\u003e`_\n-  `Twitter \u003chttp://twitter.com/etianen\u003e`_\n-  `Google Profile \u003chttp://www.google.com/profiles/david.etianen\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetianen%2Fdjango-s3-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetianen%2Fdjango-s3-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetianen%2Fdjango-s3-storage/lists"}