How to clear Mastodon media cache with tootctl

Mastodon keeps local copies of remote media so timelines and profiles can load without refetching every file from another server. On busy federated instances, older remote attachments, avatars, and profile headers can consume more storage than the posts and uploads created by local users.

The tootctl media remove task clears cached remote files by age. Its default mode removes remote media attachments, while profile avatars and headers require separate flags so account images are not pruned by accident.

Run a dry-run first and compare tootctl media usage before and after the real cleanup. The cleanup removes cached remote copies, not local user uploads, but remote files may need to be fetched again later when a timeline or profile displays them.

Steps to clear Mastodon media cache with tootctl:

Switch to the Mastodon application account.
```
$ sudo -iu mastodon
```
Open the Mastodon application directory.
```
$ cd /home/mastodon/live
```
For a container install, run the same bin/tootctl media subcommands inside the web container instead of switching to the mastodon Unix account.

Check the current Mastodon media usage.

$ RAILS_ENV=production bin/tootctl media usage
Object          Total       Local
Attachments     39.6 GB     11.8 GB
Custom emoji    128 MB      128 MB
Avatars         4.2 GB      615 MB
Headers         2.7 GB      382 MB
Preview cards   1.1 GB
Backups         0 Bytes
Settings        4.3 MB      4.3 MB

The Local column is storage owned by local accounts. The media cleanup task targets cached remote media rather than local uploads.

Preview cached remote attachment cleanup.
```
$ RAILS_ENV=production bin/tootctl media remove --days 30 --dry-run
Removed 1842 media attachments (approx. 12.4 GB) (DRY RUN)
```
–days defaults to 7. Use a longer retention window when older remote media should stay locally available for active users. Current Mastodon releases also support –keep-interacted when cached media attached to statuses favourited, bookmarked, quoted, replied to, or reblogged by local accounts should be preserved.
Remove the cached remote attachments after the dry-run matches the intended scope.
```
$ RAILS_ENV=production bin/tootctl media remove --days 30
Removed 1842 media attachments (approx. 12.4 GB)
```
Remote media can disappear permanently if the original server later deletes it or becomes unreachable. Use –dry-run and a retention window that matches the instance policy before running the destructive command.
Preview stale remote profile media cleanup if avatars and headers are part of the storage problem.
```
$ RAILS_ENV=production bin/tootctl media remove --days 30 --prune-profiles --dry-run
Visited 527 accounts and removed profile media totaling 842 MB (DRY RUN)
```
–prune-profiles removes remote avatars and headers for accounts old enough to match –days. Add –include-follows only when followed or following remote accounts should also lose cached profile media.

Remove the stale remote profile media after reviewing the dry-run.

$ RAILS_ENV=production bin/tootctl media remove --days 30 --prune-profiles
Visited 527 accounts and removed profile media totaling 842 MB

Check Mastodon media usage again.

$ RAILS_ENV=production bin/tootctl media usage
Object          Total       Local
Attachments     27.2 GB     11.8 GB
Custom emoji    128 MB      128 MB
Avatars         3.5 GB      615 MB
Headers         2.6 GB      382 MB
Preview cards   1.1 GB
Backups         0 Bytes
Settings        4.3 MB      4.3 MB

Use RAILS_ENV=production bin/tootctl media remove-orphans –dry-run only when files remain after interrupted cleanup or deleted database records. On S3 and compatible object storage, orphan scans can be slow and can incur object-listing API charges.