Change your Pi username from the command line

The fastest way to change your Raspberry Pi username is to log in as root, rename the user account, and rename the home directory. You will need physical access to your Pi or an SSH connection where you can log in as the current user. The process takes about five minutes and does not require a restart, though you should log out and back in to confirm the change worked.

Start by opening a terminal on your Pi or connecting via SSH. Type sudo su to become the root user — you will be asked for your password. Once you have the root prompt, you are ready to rename the account.

The actual rename happens in two steps. First, use usermod -l newusername oldusername to change the username itself. Replace newusername with what you want and oldusername with your current name. For example, if your current user is pi and you want to change it to james, type usermod -l james pi.

Second, rename the home directory to match. Type usermod -d /home/newusername -m newusername. This moves all your files from the old directory to the new one. Using the example above, you would type usermod -d /home/james -m james.

Key Takeaways

  • You must be logged in as root to rename a user account; use sudo su to switch to root first.
  • The usermod -l command changes the username, and usermod -d -m moves your home directory to match.
  • You should log out completely and log back in with your new username to confirm the change took effect.
  • If you cannot log in after the change, you can still access your Pi by booting into single-user mode or using a different account with sudo privileges.

Verify the change worked

After you have run both commands, type exit to leave the root prompt. Then type exit again to log out of your current session entirely. Log back in using your new username and the same password you used before.

Once you are logged in, open a terminal and type whoami. The output should show your new username. You can also type pwd to see your home directory path — it should now point to /home/newusername instead of the old path.

What happens to your files and permissions

When you use usermod -d -m, the system copies your home directory and updates the ownership of every file inside it. Your documents, scripts, and configuration files all stay in place and remain yours. The -m flag handles this automatically.

Permissions for files outside your home directory — such as files in /opt or /usr/local — are not affected by the username change. If you own files elsewhere on the system, you may need to update their ownership manually using chown newusername filename.

If the rename fails or you cannot log in

The most common reason a rename fails is that the user account is still logged in somewhere. If you see an error like "user is currently logged in", make sure you have logged out completely from all terminals and SSH sessions. You cannot rename an account that is actively running processes.

If you have already run the commands and cannot log in with your new username, you can still fix it. Reboot your Pi and hold down Shift during startup to enter the GRUB menu. Select "Advanced options" and then "Recovery mode". Once you reach the root prompt, you can run the commands again or use usermod -l oldusername newusername to revert the change.

Renaming the default pi user

Raspberry Pi OS comes with a default user called pi. Many guides recommend renaming this account for security reasons, since the username is the same on every Pi. The process is identical to renaming any other user — log in as root and run the two usermod commands.

Before you rename the pi account, check whether any scripts or cron jobs reference it by name. If you have a backup script that runs as the pi user, for example, you will need to update that reference after the rename. Search your home directory for files containing the old username by typing grep -r "pi" ~ to see what might break.

Changing the username through the GUI

Raspberry Pi OS does not have a built-in graphical tool to rename user accounts. The command line is the only supported method. However, if you are uncomfortable with the terminal, you can use a file manager to verify that your home directory has been renamed correctly after you run the commands.

Open the file manager and navigate to /home. You should see a folder with your new username. Double-check that your documents and configuration files are inside it. If you see both an old and new directory, the rename did not complete fully — go back to the terminal and run the usermod commands again.

Frequently Asked Questions

Do I need to change my password after renaming my username?

No. Your password is stored separately from your username and does not change when you rename the account. You will log in with your new username and your existing password.

What if I want to rename my username but keep the home directory path the same?

You can run usermod -l newusername oldusername without the second command. This changes the username but leaves the home directory at /home/oldusername. This is not recommended because it can confuse scripts and backups, but it is technically possible.

Can I rename a user account while it is running a long process?

No. The account must be completely logged out and have no running processes. If you have a background job or service running under that user, stop it first. You can check for running processes by typing ps aux | grep username.

Will renaming my username break my WiFi or network settings?

No. Network configuration is stored in system files that do not depend on the username. Your WiFi password and connection settings will remain intact after the rename.

What if I made a typo in the new username?

You can rename it again using the same process. Log in as root and run usermod -l correctname typoname, then usermod -d /home/correctname -m correctname. The system will handle the second rename just like the first.