Skip to main content

Change Mastodon Username

Below is a purely manual, Ruby-based procedure for “renaming” a local Mastodon account by transferring content from an old account to a newly created one in your instance’s database. Important disclaimers up front:

  • Mastodon does not officially support changing usernames by direct database manipulation; there’s no built-in UI for this.
  • In some Mastodon versions, a tootctl accounts rename command may not exist (particularly older versions).
  • Directly updating the database can be risky—always back up your DB first and proceed with caution.
  • In this example, we’re not copying (or preserving) followers/following relationships—only statuses, favorites, bookmarks, notifications, etc. The user specifically mentioned not copying followers.

If you proceed with these steps, do so in a test environment or with a fresh backup on hand.

1. Create a New Account in the Web UI

  1. Log into your Mastodon instance’s web interface as an admin.
  2. Create the new local account with the desired (target) username.
  3. Confirm you can log in to that new user in the web UI—just to be sure the account is active and recognized.

2. Prepare a Rails Console Session

  1. SSH into your Mastodon server.
  2. Switch to your Mastodon user (often mastodon or mastodon-user).
  3. Navigate to your Mastodon installation directory (e.g., /home/mastodon/live).
  4. Run:
RAILS_ENV=production bin/rails console

You should see a Ruby prompt (irb(main):001:0>) indicating you’re in the Rails console.

3. Find the Old and New Accounts

In the Rails console, find the respective Account records:

old_username = 'oldusername'  # fill in your old username
new_username = 'newusername'  # fill in your new username

# domain: nil ensures that we only match local accounts
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}"

4. Transfer Content to the New Account

You mentioned you do not want to preserve/copy followers. That’s simpler: we skip reassigning the Follow table. We’ll just move items like statuses (posts), favorites, bookmarks, notifications, etc. To do so:

# Move statuses
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 (if you want pinned statuses to show under the new account)
# Pinned statuses are in the "Pin" table
Pin.where(account_id: old_account.id)
   .update_all(account_id: new_account.id)

The above code blocks bulk update the account_id column on each table, reassigning rows from the old account to the new account.

Optional Additional Tables

Depending on your needs, you may have to consider other references:

  • Polls (if the old account created polls) 
    Poll.where(account_id: old_account.id).update_all(account_id: new_account.id)
  • Media attachments (avatars, headers, or post images could be associated with the old account or old statuses) – typically if the status is moved, the attachments should already point to that status. But if you want to fix references to the account itself: 
    MediaAttachment.where(account_id: old_account.id).update_all(account_id: new_account.id)
  • Announcements, scheduled statuses, pinned statuses etc. – depends on how thorough you need to be.

5. (Optional) “Hide” or Disable the Old Account

After you’ve verified everything is properly transferred, you can decide what to do with the old account:

  • Rename it to something like @oldusername-archived (just so you don’t have conflicts). You can do a quick Rails update in the console: 
    old_account.update!(username: "oldusername-archived")
  • Lock or suspend the old account so it’s no longer active: 
    old_account.update!(suspended_at: Time.now)
  • Or just disable the login by changing its User record (the Mastodon Account has a user_id linking to the User table). For example: 
    old_account.user.update!(disabled: true)

6. Validate the New Account

  1. Log in as the new user in the web UI.
  2. Verify that you can see the transferred posts, favorites, bookmarks, etc.
  3. Make sure any pinned statuses (if you moved them) appear correctly.
  4. Confirm the old account no longer has that content.

7. (Optional) Reindex If You Use ElasticSearch

If your instance uses ElasticSearch or advanced search, you may want to reindex to ensure that searching for statuses from the new username works properly. For example:

RAILS_ENV=production bin/tootctl search deploy

(Or use the older rake tasks if you’re on an older version.)

Important Notes

  • This process is not an official, supported “rename.” You’re effectively merging the old account’s data into a brand-new account.
  • You mentioned you specifically don’t want to copy followers/followings. That is why the snippet above omits Follow, Block, Mute, and so on.
  • Even after you move all the statuses, remote servers on the fediverse might still have cached references to the old account name for a while. That’s generally unavoidable at a protocol level.
  • Always keep a backup of your database before running these updates. One small typo can cause data corruption or undesired merges.

Summary

  1. Create the new account in the Mastodon web UI.
  2. In the Rails console, find the old and new accounts.
  3. Use update_all calls to move statuses, favorites, bookmarks, notifications, etc. from the old account to the new account.
  4. Optionally rename or disable the old account.
  5. Double-check that everything looks correct in the new account.

That’s the gist of doing it “by hand” in Ruby. Again, be cautious—direct DB-level changes are always risky! If all goes well, you end up with a new username that has the old account’s posts/favorites/etc., but without duplicating or preserving the old follow relationships.

Back to top