Executing tootctl Tasks to Purge Fediverse Database Records

By 4FreeForums Editors · Published October 30, 2026 · Sources linked below

Over time, federated community instances accumulate remote records from external servers that have gone offline, migrated, or never interacted with local members. Managing database bloat on a Mastodon server requires running maintenance tasks directly from the command line. Using the built-in administrative utility, operators can systematically identify and purge stale database records without corrupting instance relationships.

Accessing the Environment and Running tootctl

The primary administrative tool for Mastodon is an executable named tootctl, located in the bin directory of the root application checkout. On a standard deployment, this directory is found at /home/mastodon/live. Whenever you run commands through this executable, you must specify the production environment by defining the RAILS_ENV environment variable.

You can supply this variable inline for individual tasks or add it to your shell configuration so it exports automatically:

cd /home/mastodon/live
echo "export RAILS_ENV=production" >> ~/.bashrc
RAILS_ENV=production bin/tootctl help

Before executing deletion scripts on your instance, review your deployment requirements from our guide to installing Mastodon from source on Ubuntu and remember to back up your forum database to preserve core records.

Step One: Simulating and Executing Account Culls

When remote instances disappear from the fediverse, their user records often remain stored locally. The cull command audits remote accounts to determine whether they still exist on their home servers. According to the Using the admin CLI - Mastodon documentation, this command queries every remote account in the database. If the record no longer exists at the origin server, it is deleted from the database.

Accounts that have confirmed activity within the last week are excluded from these checks. If an external server cannot be reached, accounts from that origin are not removed, and the unreachable domain is reported when the command completes. You can execute this routine safely by running a trial pass first:

• Run a simulation: RAILS_ENV=production bin/tootctl accounts cull --dry-run
• Process specific domains: RAILS_ENV=production bin/tootctl accounts cull example.com
• Adjust worker threads: pass --concurrency N, which defaults to N=5 workers.

Step Two: Pruning Remote Accounts With No Local Interactions

Remote accounts frequently enter your database through federated relays, remote boosts, or public timelines without ever engaging with your local community. The prune command cleans up records that have never established a local connection.

Running tootctl accounts prune searches the database for remote accounts that never interacted with local users and deletes them. Like the cull command, it defaults to a concurrency setting of N=5 workers. Always inspect proposed removals beforehand by appending the --dry-run flag to confirm the expected record changes before writing deletions to disk.

Step Three: Purging Records Across Entire External Domains

When an entire remote server shuts down or is disconnected from your community, cleaning up individual records one by one is inefficient. The domains CLI offers a direct command to scrub all matching records associated with a remote host.

Executing tootctl domains purge DOMAIN removes all accounts associated with the specified domain without leaving database entries behind. Unlike domain suspensions, if the domain continues operating online, accounts may return to the database if they are resolved again later. For servers enforcing an allow-list, passing --limited-federation-mode removes all accounts from domains that are not allow-listed. You can also supply --by-uri to match domains in the actor URI instead of the WebFinger address, alongside the standard concurrency flag, which defaults to 5 workers.

Step Four: Removing Orphaned Custom Media and Clearing Cache

Purging remote account records can leave behind custom assets that consume database rows and disk space. You can purge external media and refresh memory stores through dedicated subcommands:

• Scrub remote emojis: execute tootctl emoji purge --remote-only to delete custom emojis belonging to remote domains while keeping local assets intact.
• Flush storage caches: run tootctl cache clear to clear out cache storage across the deployment.

Step Five: Rebuilding Database Counters and Feeds

After purging orphaned database records, relational counters and user feeds may reflect outdated totals. As documented in the Using the admin CLI - Mastodon documentation, administrators can resynchronize these values directly from the database.

The recount command updates hard-cached counters by counting referenced records from scratch. Using tootctl cache recount accounts recalculates follower, following, and status totals, while tootctl cache recount statuses recalculates reply, boost, and favourite counters. Because counting every row can take a significant amount of time depending on database size, the task supports --verbose output and --concurrency N with a default of N=5.

Finally, clear stale timeline structures with tootctl feeds clear to remove home and list feeds from Redis, then regenerate them using tootctl feeds build --all to reconstruct timelines directly from your cleaned database tables.

Sources

Using the admin CLI - Mastodon documentation

Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.