Reclaim Synapse Media Disk Space Without Breaking Shared Files

If Synapse’s media repository is filling the disk, first confirm which directory or volume is growing, then use Synapse’s supported retention settings or Admin API to remove media. Do not delete files directly from media_store: Synapse keeps media metadata in its database, and removing files behind Synapse can leave broken references or make cleanup hard to audit. The safest policy depends on whether the space is used by local uploads, cached media from other homeservers, thumbnails, or another service sharing the same disk.

What is taking the space?

Synapse’s media repository stores locally uploaded avatars, attachments, and thumbnails. It also caches media fetched from remote Matrix servers and resources used for URL previews. These are distinct from the Synapse database, container logs, and any external media repository. A full root filesystem does not by itself prove that media_store is the cause.

On the host or inside the container that owns the mounted data, compare filesystem usage with the Synapse data directory. Replace the example path with the value in your deployment:

df -h
du -h --max-depth=1 /path/to/synapse-data
du -sh /path/to/synapse-data/media_store

Synapse’s media_store_path defaults to media_store, commonly under the data directory, but installations can override it. Containers can write to a mounted volume whose actual storage is on the host. Check homeserver.yaml, your container volume mappings, or your orchestrator’s persistent-volume configuration before concluding that a host path is safe to change. If the media directory is not the largest consumer, investigate the component that du shows instead.

Choose a cleanup policy that fits the media

Verified behavior: Synapse’s media_retention setting can expire local media and cached remote media after periods without access. Access includes loading media in a room or downloading it. If an item has never been accessed, Synapse uses its creation time. Both the original media and its thumbnails are removed. Cleanup runs on the media repository worker, which may be the main Synapse process.

What depends on your use case: Remote cached files can generally be fetched again from their originating homeserver when requested after removal. Locally uploaded files are hosted by your server, so purging them can make old attachments or avatars unavailable. Choose local retention only if your users accept that consequence; a longer local lifetime or no automatic local cleanup may be more appropriate for a community that treats old attachments as an archive.

What retention does not mean: quarantining media blocks access but does not delete the file or its thumbnails. It will not free the disk space you need. If you need to preserve a quarantined item while removing other data, keep the distinction clear: quarantine is a moderation control, while retention and deletion are storage controls.

Enable automatic retention in Synapse

Back up the active configuration before editing it. Add a top-level media_retention section or update the existing one. For example, this policy expires local media after 180 days without access and remote cache entries after 30 days:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

These values are examples, not universal recommendations. Set the local period according to your retention obligations and expectations for old room content. If you only want to control the cache for remote media, configure just remote_media_lifetime; an unset or null lifetime means that type will not be purged automatically. Synapse also documents that quarantined media and local media protected from quarantine are excluded from retention cleanup.

Apply the configuration using the deployment’s normal restart or reload process, and verify that the media repository worker is running with enable_media_repo: true. If Synapse uses a separate media worker, configure the policy where the media repository service is enabled. A valid YAML edit does not immediately reclaim all space: the worker must run cleanup, and only media older than the chosen access cutoff qualifies.

Reclaim space sooner with the Admin API

If the disk is already critical, Synapse provides administrative endpoints for cleanup. These actions permanently remove media. Before using them, back up the database and media data, confirm that the URL targets your own homeserver, and use a server administrator access token over HTTPS. Keep the token out of shell history and shared logs.

To purge old cached remote media, call the documented endpoint with a cutoff timestamp in milliseconds since the Unix epoch:

POST /_synapse/admin/v1/purge_media_cache?before_ts=<unix_timestamp_in_ms>

For example, a shell can calculate a cutoff 30 days ago with GNU date:

cutoff=$(date -u -d '30 days ago' +%s000)
curl -X POST "https://matrix.example.com/_synapse/admin/v1/purge_media_cache?before_ts=$cutoff" \
  -H "Authorization: Bearer YOUR_SERVER_ADMIN_ACCESS_TOKEN"

The response reports how many cached items were deleted. If users request those remote files again, Synapse will fetch them again from the originating server; this can restore disk usage for popular media.

The local media deletion API can delete local media based on last access time and, optionally, a minimum size. Its current endpoint is POST /_synapse/admin/v1/media/delete?before_ts=…; the older endpoint containing <server_name> is deprecated since Synapse 1.78.0. The cutoff is last access, not upload date, and the keep_profiles option defaults to true. Because this deletion can remove files users expect to remain available, prefer configured retention unless you have identified an appropriate cutoff and accept the effect. Follow the official API reference for parameters and your installed Synapse version.

Common misconceptions to avoid

  • “Deleting a room will clear its media.” Do not assume this. Room history, media files, and cached copies are managed through different operations. Use the media Admin API or retention policy to manage media specifically.
  • “Quarantine frees disk space.” It does not: quarantined media and thumbnails remain on disk. Use a deletion or retention operation when storage reclamation is the goal.
  • “All media in the repository is my users’ uploads.” The repository also includes remote cache and URL preview data. Compare repository subdirectories and Synapse’s storage configuration before choosing a purge.
  • “Deleting files manually is equivalent to Synapse cleanup.” It is not a supported substitute. Let Synapse update its metadata through its retention process or Admin API.

Verify that disk usage is falling

After the cleanup worker has had time to run, check df -h and the media directory size again. For an API purge, confirm the response’s deleted count and compare the relevant directory before and after. Check Synapse logs for configuration or worker errors. If the directory remains large, inspect whether your deployment writes media to a configured provider or separate volume; the Synapse local media deletion API does not affect media stored in an external media repository. Do not assume a successful API response will reduce the host filesystem if the files live elsewhere.

Official references

Leave a Comment

Reclaim Synapse Media Disk Space Without Breaking Shared Files

Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.

Deactivate Inactive Matrix Users Without Deleting Room History

Deactivate Inactive Matrix Users Without Deleting Room History

Review device activity, deactivate confirmed inactive Synapse accounts through the Admin API, and learn what the optional erase flag actually removes.

Reduce PostgreSQL Memory Pressure in Matrix Synapse

Find whether PostgreSQL memory comes from query work, shared buffers, connections, or maintenance, then make targeted Synapse-safe changes.

Why Matrix Synapse Room Joins Are Slow—and What to Check

Why Matrix Synapse Room Joins Are Slow—and What to Check

Trace slow Matrix room joins to one remote homeserver, federation backoff, local database load, or an outbound sender queue before changing Synapse settings.

Close Matrix Sign-Ups or Require Invite Tokens on Synapse

Stop open account creation on a self-hosted Synapse server, or keep sign-ups invite-only with limited-use registration tokens.

Element Session Identity Warning: Verify Your Login Safely

Clear Element's unverified-session warning using a trusted device or recovery key, with checks that protect your encrypted chat history.

Stop ownCloud File Lock Timeouts with the Right Backend

Distinguish database lock contention from expired WebDAV locks, then choose and configure the right ownCloud 10 fix.

What to Check When ownCloud Web Opens to a Blank Page

What to Check When ownCloud Web Opens to a Blank Page

Trace a blank ownCloud Web screen to browser cache, missing web assets, service errors, or reverse-proxy URL settings with targeted checks.

Clear the ownCloud PHP Memory Warning in the Correct Runtime

Set ownCloud’s web PHP memory limit, restart the matching service, and verify the active value without confusing it with CLI settings or upload limits.

Troubleshoot ownCloud 10 MySQL Connection Failures

Find out whether MySQL, PHP, socket settings, or database permissions are blocking ownCloud 10, then verify a safe fix.