Skip to main content

Mastodon: Changing Username by Transferring Data

This article explains how to manually “rename” a local Mastodon account by transferring its content to a newly created account in your Mastodon instance’s database. This approach does not preserve followers/followings. It is a risky, unsupported method—proceed only if you fully understand the implications and have a complete database backup.

Important Disclaimers

  • Mastodon does not officially support direct username changes via database edits.
  • In some versions, tootctl accounts rename may not exist, leaving manual DB manipulation as your only option.
  • These steps involve low-level data changes that can break your instance if done incorrectly.
  • The instructions below focus on transferring statuses, favorites, bookmarks, notifications, etc., without copying followers.

1. Create the Target Account

  1. Log in to your Mastodon instance’s web interface as an admin.
  2. Create a new local account using the desired/target username.
  3. Confirm you can log in as this new user to ensure it is recognized in the system.

2. Access the Rails Console

  1. SSH into your Mastodon server.
  2. Switch to your Mastodon user (commonly mastodon or mastodon-user).
  3. Navigate to your Mastodon installation directory (e.g., /home/mastodon/live).
  4. Start the Rails console in production mode: 
    RAILS_ENV=production bin/rails console
  5. You should see a Ruby prompt (irb(main):001:0>).

3. Identify the Old and New Accounts

In the Rails console, look up both the old and the new Account objects:

old_username = 'oldusername'  # Replace with the old username
new_username = 'newusername'  # Replace with the new username

old_account = Account.find_by(username: old_username, domain: nil)
new_account = Account.find_by(username: new_username, domain: nil)

if old_account.nil?
  puts "Old account not found! Check old_username."
end

if new_account.nil?
  puts "New account not found! Check new_username."
end

puts "Old account ID: #{old_account.id}"
puts "New account ID: #{new_account.id}"

Note: domain: nil ensures you are finding local (rather than remote) accounts.

4. Transfer Content (Without Followers)

The following code reassigns items like statuses, favorites, bookmarks, and notifications from the old account to the new account. We are deliberately skipping follower/following relationships:

# Move statuses to the new account
Status.where(account_id: old_account.id)
      .update_all(account_id: new_account.id)

# Move favourites
Favourite.where(account_id: old_account.id)
         .update_all(account_id: new_account.id)

# Move bookmarks
Bookmark.where(account_id: old_account.id)
        .update_all(account_id: new_account.id)

# Move notifications
Notification.where(account_id: old_account.id)
            .update_all(account_id: new_account.id)

# Optionally move pinned statuses
Pin.where(account_id: old_account.id)
   .update_all(account_id: new_account.id)

Note: You can adapt this pattern for other tables, like Poll or MediaAttachment, if needed.

# Polls
Poll.where(account_id: old_account.id).update_all(account_id: new_account.id)

# Media attachments (if you want them reassigned from old to new account explicitly)
MediaAttachment.where(account_id: old_account.id).update_all(account_id: new_account.id)

5. Retire or Archive the Old Account

Once you confirm data has moved, you can:

  • Rename the old account to avoid conflicts: 
    old_account.update!(username: "oldusername-archived")
  • Suspend the old account (prevent further use): 
    old_account.update!(suspended_at: Time.now)
  • Disable the old user record: 
    old_account.user.update!(disabled: true)

6. Verify the New Account

  1. Log in as the new user in the web UI.
  2. Check that statuses, favorites, and bookmarks have transferred.
  3. Confirm pinned statuses (if any) display properly.
  4. The old account should no longer have these items.

7. Reindex (If Using ElasticSearch)

If your instance uses ElasticSearch or advanced indexing:

RAILS_ENV=production bin/tootctl search deploy

This ensures the newly transferred posts are indexed correctly.

Final Notes

  • This is not an official method to rename Mastodon accounts. The procedure effectively merges old account data into a new account.
  • We deliberately did not transfer follower relationships—those remain with the old account.
  • Remote servers may still reference the old username for a time, due to caching on the Fediverse.
  • Always keep backups of your database. Minor mistakes in database manipulation can cause significant data loss.
Back to top