Synapse S3 Storage Provider

1.6.0 verified Mon Apr 27 auth: no python

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.

pip install synapse-s3-storage-provider

Common errors

error ModuleNotFoundError: No module named 's3_storage_provider' ↓

cause The package is not installed, or installed in a different Python environment.

fix

Run pip install synapse-s3-storage-provider in the same environment as Synapse.

error synapse.s3_storage_provider import S3StorageProviderBackend ImportError: cannot import name 'S3StorageProviderBackend' from 'synapse.s3_storage_provider' ↓

cause Incorrect import path. The module is a standalone package, not part of Synapse.

fix

Use from s3_storage_provider import S3StorageProviderBackend.

error botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the PutObject operation: Access Denied ↓

cause AWS credentials do not have permission to write to the S3 bucket, or the bucket policy is restrictive.

fix

Verify IAM permissions: s3:PutObject, s3:GetObject, s3:DeleteObject on the bucket. Also check bucket policy and ACLs.

Warnings

breaking Version 1.6.0 requires Synapse 1.140.0+. Using an older Synapse will cause import errors or runtime breakage. ↓

fix Upgrade Synapse to >=1.140.0 or pin synapse-s3-storage-provider to 1.5.0.

breaking 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). ↓

fix Use the `--synapse-config` flag or set the `SYNAPSE_CONFIG_PATH` environment variable to point to your homeserver.yaml.

deprecated Support for Python 3.9 and earlier was dropped in favor of 3.10+. Check Python version before upgrading. ↓

fix Upgrade to Python 3.10 or later.

gotcha 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. ↓

fix Include `session_token: YOUR_SESSION_TOKEN` in the config if using temporary AWS credentials.

Imports

S3StorageProviderBackend
```
from s3_storage_provider import S3StorageProviderBackend
```
Correct import for the main storage provider class.

S3StorageProvider

wrong

from synapse.s3_storage_provider import ...

correct

from s3_storage_provider import S3StorageProviderBackend

No module named 'synapse.s3_storage_provider'; this is a separate package.

Quickstart

Basic configuration example for Synapse's homeserver.yaml. The module is loaded automatically by Synapse; manual instantiation is for testing.

# In Synapse's homeserver.yaml under the `media_store` section:
# media_store:
#   storage_providers:
#     - module: s3_storage_provider.S3StorageProviderBackend
#       store_local: True
#       store_remote: True
#       store_synchronous: False
#       config:
#         bucket: my-matrix-media-bucket
#         region_name: us-east-1
#         # Optional: access_key_id: YOUR_ACCESS_KEY
#         # Optional: secret_access_key: YOUR_SECRET_KEY
#         # Optional: session_token: YOUR_SESSION_TOKEN
#         # Optional: prefix: myprefix/
#         # Optional: endpoint_url: https://s3.custom-endpoint.com
import os
from s3_storage_provider import S3StorageProviderBackend

# Example: creating an instance manually (not typical, usually via Synapse config)
backend = S3StorageProviderBackend(
    config={
        "bucket": "my-bucket",
        "region_name": "us-east-1",
        "access_key_id": os.environ.get('AWS_ACCESS_KEY_ID', ''),
        "secret_access_key": os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
    }
)