Documentation

Requirements

• WordPress 5.3 or later (tested up to 7.1).
• PHP 7.0 or later.
• An administrator account with the manage_options capability. On multisite, renaming other users needs manage_network_users.

Install

1. In your dashboard, go to Plugins > Add New and search for SmartUsername.
2. Click Install Now, then Activate.
3. Open Users > Change Username.

With WP-CLI:

wp plugin install smartusername --activate

You can also download the zip from WordPress.org and upload it from Plugins > Add New > Upload Plugin.

Rename a user

1. Go to Users > Change Username. You can also click Change username under a name on the Users screen, or the button next to the Username field on a profile.
2. Choose the user and type the new username. The live check shows whether the name is valid and free as you type.
3. Choose the options you want:
   • Also update the author URL slug: the new slug comes from the display name, and the old author URL redirects with a 301.
   • Keep the old username as a trap: later login attempts with the old name are refused and counted.
   • Email the user their new username: a short email with the old and new username and the login link.
4. Click Change Username.

Posts, comments, role, password and user meta stay attached, because they are linked to the user ID, which does not change. The rename is only reported as done when the database row was actually updated. The user’s open sessions end, so they log in again with the new name. Email login keeps working.

Username rules

SmartUsername uses the same rules as WordPress core: at most 60 characters; letters, numbers, spaces and . - _ @ only. Names blocked by the illegal_user_logins filter are refused. Input is checked with sanitize_user() in strict mode and validate_username(). If anything cannot be saved, you get an admin notice and nothing is changed.

Rename your own account

Tick the confirmation box before you submit. You are signed out and log in again with the new username or your email address. A message on the login screen tells you the change worked.

Exposure check and login name protection

The Exposure check card on the Change Username screen shows every place a visitor can read login names, each with a Hidden or Exposed verdict and a button to fix it:

Turn on Login name protection to close them all with one switch. If your site does not need author pages, an extra switch turns off author archives too.

Check from outside. The free Username Exposure Checker scans your site’s public pages the way an attacker would, so you can confirm the result.

Trap usernames

Nobody can log in with a name that no account uses, so every attempt with one is a bot. SmartUsername treats admin (when no account has that name) and old usernames you choose to keep as traps. Attempts are refused with the normal error and counted on the Login attacks caught Dashboard widget. No IP addresses are stored. If you later create a real account with a trap name, the trap stops applying to it.

Risky username alert

The Dashboard and Users screens warn when an account uses a username that login attacks guess first, such as admin, administrator, root or your site name, with a one-click Rename button. You can dismiss the notice; it only returns if something new is found. Developers can change the list with the smartusername_risky_usernames filter.

Self-service renames

Off by default. To let users change their own username, tick Allow users to change their own username under Self-service renames, choose the roles and set the number of days between changes. Those users then see Profile > Change Username.

Rename log

The latest 50 changes are listed on the screen: old and new username, author slugs, who made the change (an administrator, the user or WP-CLI) and whether the email was sent. Clear log empties it. The log lives in your own database.

WP-CLI commands

Users can be given as an ID, username or email address.

# Check a name without changing anything
wp smartusername check <user> <new-username>

# Rename, optionally update the author slug and email the user
wp smartusername rename <user> <new-username> [--slug] [--notify]

# Where are login names visible? (table or json)
wp smartusername exposure [--format=<format>]

# Recent changes
wp smartusername log [--format=<format>]

Example:

$ wp smartusername rename 12 jane.writer --slug
Success: Username changed from jane to jane.writer.

Hooks and filters

add_action( 'smartusername_username_changed', function ( $user_id, $old, $new ) {
	error_log( "User $user_id renamed from $old to $new" );
}, 10, 3 );

Multisite

SmartUsername works on multisite for users who are not network super admins. Usernames are shared by the whole network, so renaming other users needs manage_network_users. Activate it per site or network activate it.

Uninstall

Deleting the plugin removes the rename log, the settings, trap names and counts, the stored old author slugs used for redirects, and the small per-user markers for self-service and dismissed notices.

Troubleshooting

The outside checker says Partly hidden

Your theme probably links to author pages, so author slugs are public. After Fix author slugs they come from display names, not logins. To keep author slugs out of public pages too, turn off author archives if you do not need them.

The user did not get the email

The screen tells you if your site could not send it. Most hosts need an SMTP plugin for reliable email.

Another plugin needs the public users list

Leave Login name protection off and fix the other items one by one from the Exposure check card.

Still stuck? See Support.