---
id: synapse-s3-storage-provider
version: "1.6.1"
license: unclear
license_treatment: permissive
maintenance: active
---

# synapse-s3-storage-provider — A storage provider which can fetch and store media in Amazon S3.

License: permissive · Maintenance: active · Downloads: 137.9K/mo

## What it is and what it does

This package is a Synapse storage provider plugin that redirects media storage and retrieval to Amazon S3 or S3-compatible object storage services. Instead of storing media files on local disk, Synapse can be configured to push media to S3 and fetch it on demand, enabling scalable, distributed media management for Matrix homeservers.

The plugin integrates with Synapse's media storage system via configuration in homeserver.yaml. It supports optional features like server-side encryption with customer-provided keys, configurable storage classes (e.g., STANDARD_IA for cost optimization), object prefixes for multi-tenant bucket sharing, and tunable thread pool sizes. It also includes a companion script (s3_media_upload) for asynchronous bulk uploads and cleanup of local media after archival to S3.

Use it for:

- Run a Matrix homeserver with media stored on S3 instead of local disk, enabling horizontal scaling and shared storage across multiple server instances.
- Archive old media from a Synapse instance to S3 using the s3_media_upload script, then delete local copies to reclaim disk space.
- Use an S3-compatible service (MinIO, DigitalOcean Spaces, etc.) as a media backend when AWS S3 is not available or desired.
- Implement cost-effective media storage by configuring S3 storage classes like STANDARD_IA for infrequently accessed media.
- Share a single S3 bucket across multiple Synapse instances using the prefix configuration option.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Synapse media storage provider that integrates Amazon S3 (or S3-compatible services) as a backend for storing and retrieving media files.

Yes. This is an actively maintained, low-friction plugin for a specific and well-defined use case: offloading Synapse media storage to S3. It has no known vulnerabilities, permissive licensing, and stable dependencies. Install it if you run Synapse and want S3-backed media storage; skip it if you use local disk storage or a different homeserver.

## Install

pip install synapse-s3-storage-provider
uv add synapse-s3-storage-provider
poetry add synapse-s3-storage-provider

## Installing synapse-s3-storage-provider

Before you install: Low friction install with a pure-Python wheel. Actively maintained with a recent release; last commit was 2026-08-14. Depends on boto3, botocore, and several other stable libraries (Twisted, psycopg2, PyYAML, humanize, tqdm).

License in practice: Licensed under Apache License 2.0 (permissive). You can use, modify, and distribute this package freely in both open-source and commercial projects, with minimal restrictions.

Quickstart:

pip install synapse-s3-storage-provider

# Add to synapse config (homeserver.yaml):
media_storage_providers:
- module: s3_storage_provider.S3StorageProviderBackend
  store_local: True
  store_remote: True
  config:
    bucket: your-bucket-name
    region_name: us-east-1

Requires Python 3.10 or later. Synapse must be installed and running; this is a plugin, not a standalone tool. AWS credentials must be configured (via environment, IAM role, or config file) for boto3.

Verify before relying:

- Performance characteristics and throughput limits when handling large media volumes or concurrent uploads.
- Compatibility with specific versions of Synapse beyond the general requirement that it be installed.
- Whether the included s3_media_upload script supports incremental or resumable uploads for very large media stores.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 137.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

synapse s3 storage, matrix media s3 backend, s3 storage provider, synapse media storage, amazon s3 integration synapse, s3-compatible media storage, matrix homeserver s3, matrix-homeserver, s3-storage, media-backend

[View on SkillFed](https://skillfed.io/packages/synapse-s3-storage-provider) · [View on PyPI](https://pypi.org/project/synapse-s3-storage-provider/)