{"id":22432,"library":"synapse-s3-storage-provider","title":"Synapse S3 Storage Provider","description":"A storage provider for Synapse, the Matrix homeserver, which fetches and stores media in Amazon S3 (or compatible object stores). Version 1.6.0 requires Synapse 1.140.0+. Released irregularly.","status":"active","version":"1.6.0","language":"python","source_language":"en","source_url":"https://github.com/matrix-org/synapse-s3-storage-provider","tags":["matrix","synapse","s3","storage","media"],"install":[{"cmd":"pip install synapse-s3-storage-provider","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required at runtime; interacts directly with Synapse storage layer.","package":"matrix-synapse","optional":false},{"reason":"AWS SDK for Python; required for S3 operations.","package":"boto3","optional":false}],"imports":[{"note":"Correct import for the main storage provider class.","symbol":"S3StorageProviderBackend","correct":"from s3_storage_provider import S3StorageProviderBackend"},{"note":"No module named 'synapse.s3_storage_provider'; this is a separate package.","wrong":"from synapse.s3_storage_provider import ...","symbol":"S3StorageProvider","correct":"from s3_storage_provider import S3StorageProviderBackend"}],"quickstart":{"code":"# In Synapse's homeserver.yaml under the `media_store` section:\n# media_store:\n#   storage_providers:\n#     - module: s3_storage_provider.S3StorageProviderBackend\n#       store_local: True\n#       store_remote: True\n#       store_synchronous: False\n#       config:\n#         bucket: my-matrix-media-bucket\n#         region_name: us-east-1\n#         # Optional: access_key_id: YOUR_ACCESS_KEY\n#         # Optional: secret_access_key: YOUR_SECRET_KEY\n#         # Optional: session_token: YOUR_SESSION_TOKEN\n#         # Optional: prefix: myprefix/\n#         # Optional: endpoint_url: https://s3.custom-endpoint.com\nimport os\nfrom s3_storage_provider import S3StorageProviderBackend\n\n# Example: creating an instance manually (not typical, usually via Synapse config)\nbackend = S3StorageProviderBackend(\n    config={\n        \"bucket\": \"my-bucket\",\n        \"region_name\": \"us-east-1\",\n        \"access_key_id\": os.environ.get('AWS_ACCESS_KEY_ID', ''),\n        \"secret_access_key\": os.environ.get('AWS_SECRET_ACCESS_KEY', ''),\n    }\n)","lang":"python","description":"Basic configuration example for Synapse's homeserver.yaml. The module is loaded automatically by Synapse; manual instantiation is for testing."},"warnings":[{"fix":"Upgrade Synapse to >=1.140.0 or pin synapse-s3-storage-provider to 1.5.0.","message":"Version 1.6.0 requires Synapse 1.140.0+. Using an older Synapse will cause import errors or runtime breakage.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"Use the `--synapse-config` flag or set the `SYNAPSE_CONFIG_PATH` environment variable to point to your homeserver.yaml.","message":"The database configuration must be read from Synapse's homeserver.yaml by default. Ensure the YAML file is accessible to the script (e.g., s3_media_upload).","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Upgrade to Python 3.10 or later.","message":"Support for Python 3.9 and earlier was dropped in favor of 3.10+. Check Python version before upgrading.","severity":"deprecated","affected_versions":">=1.6.0"},{"fix":"Include `session_token: YOUR_SESSION_TOKEN` in the config if using temporary AWS credentials.","message":"The `session_token` parameter (added in v1.6.0) is optional but critical for STS-based credentials. Omitting it when using temporary credentials will cause authentication failures.","severity":"gotcha","affected_versions":">=1.6.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `pip install synapse-s3-storage-provider` in the same environment as Synapse.","cause":"The package is not installed, or installed in a different Python environment.","error":"ModuleNotFoundError: No module named 's3_storage_provider'"},{"fix":"Use `from s3_storage_provider import S3StorageProviderBackend`.","cause":"Incorrect import path. The module is a standalone package, not part of Synapse.","error":"synapse.s3_storage_provider import S3StorageProviderBackend ImportError: cannot import name 'S3StorageProviderBackend' from 'synapse.s3_storage_provider'"},{"fix":"Verify IAM permissions: s3:PutObject, s3:GetObject, s3:DeleteObject on the bucket. Also check bucket policy and ACLs.","cause":"AWS credentials do not have permission to write to the S3 bucket, or the bucket policy is restrictive.","error":"botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the PutObject operation: Access Denied"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}