How to Change Your GitHub Username (And What Happens When You Do)
Changing your GitHub username is straightforward — but the downstream effects can ripple further than most people expect. Before you make the switch, it's worth understanding exactly what changes, what breaks, and what you'll need to fix manually.
How to Change Your GitHub Username
GitHub allows you to change your username directly from your account settings. Here's the path:
- Log in to GitHub
- Click your profile photo in the top-right corner
- Go to Settings
- In the left sidebar, select Account
- Under the "Change username" section, click Change username
- Enter your new username and confirm
GitHub will warn you about the consequences before you proceed. Read that warning — it lists the specific things that will and won't carry over automatically.
What GitHub Automatically Redirects
GitHub does handle some of the transition for you. When you change your username:
- Profile URL — Your old github.com/oldusername URL will redirect to your new profile, but only as long as no one else claims that old username
- Repository URLs — Links to your repositories redirect automatically under the same condition
- Gists — These also redirect, following the same logic
The key phrase there is as long as no one else claims that old username. GitHub username redirects are not permanent guarantees. The moment someone else registers your old username, your redirects break.
What Does NOT Transfer Automatically ⚠️
This is where most people run into trouble. Several things will break or need manual attention:
| What Breaks | Why |
|---|---|
| Git remote URLs on local machines | Still point to your old username |
| Hardcoded links in README files | Won't update automatically |
| Package registry references (npm, PyPI, etc.) | Must be updated manually |
| GitHub Pages custom domain configs | May need reconfiguration |
| Third-party integrations and webhooks | Often authenticated by username path |
| CI/CD pipeline scripts | Any hardcoded repo paths will fail |
| Badges (e.g., shields.io) | Require updated URLs |
If your repositories are referenced inside other projects — especially open source ones — contributors will start hitting 404s or redirect chains until they update their local remotes.
Updating Your Local Git Remotes
After changing your username, every local clone of your repositories still points to the old URL. You'll need to update each one manually.
To check your current remote: