Configurable cleanup of your toot history on Mastodon.
Go to file
2022-01-02 19:29:30 +01:00
.github/workflows Test against python 3.10 2021-12-19 13:59:36 +01:00
cleantoots Add and run pre-commit 2021-12-19 14:21:43 +01:00
tests Add and run pre-commit 2021-12-19 14:21:43 +01:00
.flake8 Add and run pre-commit 2021-12-19 14:21:43 +01:00
.gitignore Add and run pre-commit 2021-12-19 14:21:43 +01:00
.pre-commit-config.yaml Add and run pre-commit 2021-12-19 14:21:43 +01:00
_config.yml Add and run pre-commit 2021-12-19 14:21:43 +01:00
LICENSE Update 'LICENSE' 2022-01-01 22:27:36 +01:00
poetry.lock Fix urllib3 2021-12-19 15:00:39 +01:00
pyproject.toml Update license classifiers & bump version 2022-01-01 22:43:55 +01:00 Update '' 2022-01-02 19:29:30 +01:00 Add and run pre-commit 2021-12-19 14:21:43 +01:00


Build Status

Cleantoots helps you delete your old toots. Because not everything we say on social medias should stay there for eternity.

Useful links:


Using pip

python -m pip install cleantoots

ArchLinux package

An ArchLinux package is available, see the AUR.


Initial setup

Only once

cleantoots config setup  # See the following section for config file options
cleantoots config login

View and edit

You can later view the parsed config file with

cleantoots config list

You can edit the config file using

cleantoots config edit

This will open the config file using your preferred editor (EDITOR env variable).

Config options

# Any key in this section will serve as a default for other sections

# Toots that have at least this number of boosts won't be deleted.
boost_limit = 5

# Toots that have at least this number of favorites won't be deleted.
favorite_limit = 5

# Toots that are more recent than this number of days won't be deleted.
days_count = 30

# The timezone to use for dates comparisons.
timezone = Europe/Paris

# Each section represents an account.
# Your Mastodon server URL.
api_base_url =

# These files are used to store app information obtained when running `login`.
# The files must be different between accounts. Two different files are required per account.
app_secret_file = fosstodon_app.secret
user_secret_file = fosstodon_user.secret

# IDs of toots you want to protect (never delete).
# You can find the toot ID in the URL when viewing a toot.
protected_toots = 103362008817616000

# Tags you want to protect (never delete).
# Tags are matched case insensitively and are only matched for original toots (not for boosts):
# if you boost a toot containing #ScreenshotSunday it won't be protected by this rule.
# You MUST omit the `#` part of the tag.
protected_tags = 100DaysToOffload

# Another account
api_base_url =
app_secret_file = mastodonsocial_app.secret
user_secret_file = mastodonsocial_user.secret

# Overriding some defaults
boost_limit = 10
favorite_limit = 30
days_count = 7


See cleantoots config for the current config.

cleantoots clean  # Defaults to a dry run. Does NOT delete.
cleantoots clean --delete  # Delete without prompt.

Add an account

cleantoots config edit  # Opens editor so you can add your config
cleantoots config list  # Check your newly added account
cleantoots config login --only-missing  # Store credentials for your newly created account
cleantoots clean --delete

Remove an account

# This deletes stored credentials for accounts described in the main config file.
cleantoots config clear-credentials

# You can then edit the config and remove some accounts:
cleantoots config edit

# Then login again for remaining accounts.
cleantoots config login

Tested environments

Cleantoots test suite runs on Python 3.7, 3.8 and 3.9 on latest versions of macOS, Windows and Ubuntu as GitHub Actions understands it.

See the docs for more information on what "latest" means.

Similar projects

  • ephemetoot: A similar python-based CLI program to delete your old toots. Has the ability to archive deleted toots.


The idea behind cleantoots is highly inspired by magnusnissel/cleantweets.


If you do reuse my work, please consider linking back to this repository 🙂