How to Rename a GitHub Repository (and What Breaks)
To rename a GitHub repository, open the repository on github.com, click Settings, type the new name in the Repository name field at the top of the General page and click Rename. GitHub redirects the old URL, so existing links and clones keep working, but you should still point your local clone at the new address with git remote set-url origin <new-url>.
You need admin access to the repository (or be an owner of the organization that owns it). The rename takes effect immediately. The rest of this guide covers the command-line alternative, what GitHub redirects for you, the things that don't redirect (GitHub Pages project sites and GitHub Actions in particular), and how renaming differs from transferring.
Rename a repository on github.com
- Go to the repository's main page.
- Click Settings in the repository tabs. If you don't see it, open the ... menu at the end of the tab row and click Settings.
- On the General page, find the Repository name field at the top.
- Type the new name.
- Click Rename.
Stick to letters, numbers, hyphens, underscores and periods. GitHub converts other characters, such as spaces, to hyphens, so My Project becomes My-Project.
The name must be unique within the account or organization, so you can't rename to a name that one of your other repositories already uses.
Rename with the GitHub CLI
If you use the gh command-line tool, run this inside the repository:
gh repo rename new-nameOr rename a repository from anywhere:
gh repo rename -R owner/old-name new-nameYou give only the new name, not the owner; gh repo rename cannot move a repository to a different account. Afterwards, run git remote -v to confirm your clone's origin points at the new name, and update it as shown below if it doesn't.
Update your local clone
GitHub keeps redirecting git clone, git fetch and git push from the old location, so nothing breaks right away. Still, GitHub recommends updating the remote, and it avoids trouble if the redirect ever stops working (see the next section). In each clone:
git remote -v
git remote set-url origin https://github.com/OWNER/new-name.git
git remote -vIf you use SSH, use the SSH form of the URL:
git remote set-url origin git@github.com:OWNER/new-name.gitThe local folder name doesn't change. Your clone still lives in old-name/ on disk until you rename that folder yourself, which is safe to do: Git doesn't care what the folder is called. See how to rename a folder on Mac or how to rename a file if you need the steps for your system.
What GitHub redirects
According to GitHub's documentation, after a rename all existing information is redirected to the new name, with the exception of project site URLs. That includes:
- The repository's web pages, issues, pull requests and wiki.
- Stars and watchers, which stay with the repository.
- Git operations (clone, fetch, push) that use the old URL.
These redirects last until something else takes the old name.
Don't reuse the old name
If you create a new repository with the old name in the same account, the redirects stop, because the old URL now belongs to the new repository. Clones still pointing at the old URL would start pulling from, and pushing to, the wrong repository. Update remotes before reusing a name, or simply don't reuse it.
What breaks after a rename
GitHub Pages project sites
A project site is served at https://OWNER.github.io/REPO/, and GitHub doesn't redirect it when the repository is renamed. The site moves to the new path and the old URL stops working. If people link to your site, use a custom domain, which is unaffected by repository renames. Also check the site's own configuration for a hard-coded base path (for example a baseurl or base setting in your static site generator) that still contains the old name.
A user or organization site is different: its repository must be named OWNER.github.io, so renaming that repository to anything else stops it from being the user site.
Actions hosted in the repository
If the repository contains a GitHub Action that other workflows use, as in uses: OWNER/old-name@v1, those calls are not redirected. Workflows that reference the old name fail with a "repository not found" error. GitHub's advice for an action that others depend on is to create a new repository with the new name and archive the old one, rather than renaming.
Workflows inside the renamed repository itself keep running; they don't refer to their own repository by name unless you wrote it into them.
Hard-coded names elsewhere
Anything that spells out the old name works through the redirect at best, and some tools don't follow redirects. Search for the old name in:
- README badges and links.
package.jsonrepositoryandhomepagefields, and similar metadata in other ecosystems.- Go module paths in
go.mod, since the repository name is part of the import path. - CI and deploy configuration, webhooks and third-party integrations.
- Documentation and links on other sites.
Rename vs transfer
Renaming changes the repository's name but keeps the owner. Transferring changes the owner (from your account to an organization, for example) and can keep the same name. They live in different places:
| Action | Where | Who can do it |
|---|---|---|
| Rename | Settings > General > Repository name | Repository admins, organization owners |
| Transfer | Settings > General > Danger Zone > Transfer ownership | Repository admins, subject to the target account's permissions |
Both create redirects from the old URL. If you want both a new owner and a new name, transfer first and rename after, or the other way round; either works.
Renaming a branch instead
If what you want to change is master to main, or another branch name, you don't need to rename the repository at all. See how to rename a Git branch, which covers GitHub's branch rename button and the commands for local clones.
Choosing a good repository name
A repository name becomes part of URLs, clone folders and sometimes package names, so it pays to choose one you won't need to change:
- Lowercase words separated by hyphens, such as
invoice-parser, read well in URLs and avoid case confusion on different file systems. - Describe what the code does rather than a project codename that newcomers won't recognise.
- Avoid version numbers or years unless the repository really is tied to one.
Our naming conventions guide covers kebab-case and the other common styles, and the same thinking applies to file naming.
Frequently Asked Questions
How do I rename a repository on GitHub?
Open the repository, click Settings, type the new name in the Repository name field on the General page and click Rename. You need admin access to the repository. With the GitHub CLI you can run gh repo rename new-name from inside the clone.
Do I need to update my local Git remote after renaming a repository?
It isn't urgent, because GitHub redirects clone, fetch and push from the old URL. It is still recommended: run git remote set-url origin followed by the new URL, then git remote -v to check. This protects you if a new repository is ever created with the old name.
Will renaming a GitHub repository break links?
Links to the repository, its issues, pull requests and wiki redirect to the new name. GitHub Pages project site URLs do not redirect, and workflows that use an action hosted in the repository stop resolving it. Creating a new repository with the old name also breaks all redirects.
Do I lose stars, issues or history when I rename a repository?
No. Stars, watchers, issues, pull requests, wiki pages and the full commit history all stay with the repository. Only the name and URL change.
What is the difference between renaming and transferring a repository?
Renaming changes the repository name under the same owner. Transferring moves the repository to a different user or organization, optionally keeping its name. Both are in the repository settings, and both redirect the old URL.
Who can rename a GitHub repository?
People with admin permission on the repository, and owners of the organization that owns it. Collaborators with write access cannot rename it.
Related Posts
How to Rename a Git Branch (Local and Remote)
Rename a Git branch with git branch -m, then update the remote: push the new name, delete the old one, reset upstream tracking and update teammates and GitHub.
AdvancedHow to Rename Columns in pandas (df.rename and 6 Other Ways)
Rename columns in pandas with df.rename(columns={...}), replace all names with df.columns, clean names with str methods, and avoid silent KeyErrors and inplace.
GuideHow to Rename a Column in Google Sheets (What Actually Works)
Google Sheets column letters can't be renamed, but you can name columns with a header row, a named range or a table. Step-by-step for each, plus freezing.
Ready to organize your files?
Try AI renaming right away. No sign-up needed until you download.
Try It Free