--- title: How do I change the name of my Vercel Project? description: Change your Vercel project name in the dashboard, CLI, or REST API, then update the environment variables, callbacks, and hooks that store the old name. url: /kb/guide/how-to-change-vercel-project-name canonical_url: "https://vercel.com/kb/guide/how-to-change-vercel-project-name" last_updated: 2026-07-27 authors: Vercel related: - /docs/project-configuration/general-settings - /docs/cli/project - /docs/rest-api/reference/endpoints/projects/update-an-existing-project - /docs/cli/project-linking - /docs/deployments/generated-urls - /docs/projects/managing-projects install_vercel_plugin: npx plugins add vercel/vercel-plugin --- Renaming a Vercel project takes one action in the dashboard, CLI, or REST API. The rename itself is safe. Git auto-deploys, CI/CD pipelines, and local project links all run on an immutable project ID, so they keep working untouched. The work that remains is updating the places where the old project name was stored as a string, then confirming the change propagated. Here's how to rename a project, why the pipeline stays intact, and what to update afterwards. ## How to change a Vercel project name Every rename path performs the same operation, so pick the one that fits your workflow. Use the dashboard for a one-off change, or the CLI and REST API when the rename needs to run inside a script or an automated process. ### Rename from the dashboard For a one-off rename while you're signed in, use the dashboard: 1. Open your project in the [Vercel dashboard](https://vercel.com/dashboard). 2. Select **Settings** in the top navigation. 3. Select **General** in the settings sidebar. This is project settings, which is separate from account settings. 4. Edit the name in the name field. 5. Select **Save**. Vercel confirms the change. Project names must be lowercase, up to 100 characters, and limited to letters, digits, and the characters `.`, `_`, and `-`, with no `---` sequence. New deployments start using the new name right away. See the [project naming rules](https://vercel.com/docs/project-configuration/general-settings) for the full constraints. ### Rename with the Vercel CLI For terminal workflows and scripts, rename with the Vercel CLI: `vercel project rename ` For example, to rename `my-project`: `vercel project rename my-project my-renamed-project` The `vercel project` subcommand also covers `list`, `add`, `inspect`, `update`, and `remove`. The `--name` flag on `vercel deploy` is deprecated in favor of project linking, so use the dedicated `rename` subcommand for renames. ### Rename with the REST API For programmatic renames across many projects, call the update-project endpoint: `curl -X PATCH "" \ -H "Authorization: Bearer $VERCEL_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my-renamed-project" }'` The `idOrName` parameter accepts the current name or the project ID. Pass the project ID (`prj_...`) so the call stays valid no matter the current name. Add `teamId` or `slug` as a query parameter when you act on behalf of a team. A successful rename returns HTTP 200 with the updated project object. ## Why renaming doesn't break your Vercel deployments Every Vercel project has two identities, and understanding the split explains why the rename is safe. The name is the mutable label Vercel shows in the dashboard and uses in generated `*.vercel.app` URLs. The project ID (`prj_...`) is immutable, and the platform uses it for routing and for the links your local project and pipelines depend on. When you run `vercel link`, Vercel writes a `.vercel/project.json` file that stores your `orgId` and `projectId`. The project name never appears in that file, so renaming changes nothing about what your local directory points to. The same holds in CI, where the `VERCEL_PROJECT_ID` secret stores the `prj_...` value and makes pipelines built on it rename-safe by design. The risk comes from treating the project name as a stable technical identifier. Anything that stored the old name as a string needs a manual update, which is what the next section covers. ## **What to update after you rename a Vercel project** Anything that runs on the project ID survives the rename with no action from you. Anything that stored the old project name, or a URL built from it, needs a manual update. Vercel changes the name, not the values saved in your environment variables or at third-party services, so audit those yourself before and after the rename. Work through these four categories: - **Environment variables with the old domain:** Update any variable that hardcodes the old `.vercel.app` URL, such as `NEXTAUTH_URL`, `AUTH_REDIRECT_URI`, or `NEXT_PUBLIC_APP_URL`. Vercel doesn't rewrite these values. - **OAuth callback URLs:** Update the allowed callback URLs at each identity provider. A callback that still points to the old URL fails the redirect-URI match and blocks sign-in. - **Deploy hooks shared externally:** Revoke and recreate any deploy hook URL that external systems call, then update the stored value at each caller. - **Cross-project references in a monorepo:** Update environment variables in sibling projects that reach the renamed project by its old URL. The table below shows the full breakdown of what a rename affects and where you need to act: | Item | Status after rename | Action required | | ---------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- | | Git integration and auto-deploys | Unaffected; runs on the project ID | None | | `VERCEL_PROJECT_ID` in CI secrets | Unaffected; the ID is immutable | None | | `.vercel/project.json` local link | Unaffected; stores `orgId` and `projectId` | Optionally re-run `vercel link` or `vercel pull` to refresh local state | | New deployment `*.vercel.app` URLs | Use the new name | Update bookmarks or external links to the old format | | Pre-rename `*.vercel.app` URLs | Not guaranteed | Don't depend on them | | Custom domains | Assigned separately from the name | Verify under Settings, then Domains | | Env vars with the old domain | Unchanged automatically | Update every variable that holds the old URL | | OAuth callback URLs | Unchanged; blocks sign-in | Update allowed callbacks at each provider | | Externally shared deploy hooks | URL value may change | Revoke and recreate, then update callers | | Third-party webhook endpoints | Not updated by Vercel | Update the stored URL at each service | | Monorepo sibling env vars | Unchanged; breaks cross-project calls | Update the URL in each sibling project | New deployments generate URLs in the `-.vercel.app` format using the new name. Vercel doesn't guarantee how pre-rename generated URLs behave, so replace any old `*.vercel.app` URL that's bookmarked, shared, or stored externally, and use a custom domain for anything production-facing. ## How to confirm your Vercel project name change After the rename, run a short verification pass to confirm it propagated everywhere. Check each surface in turn: - **Dashboard:** Reload the dashboard and confirm the project appears under the new name. - **CLI:** Run `vercel project ls` and confirm the new name is listed. - **REST API:** Send a GET request to `https://api.vercel.com/v9/projects/` and confirm it returns HTTP 200 with the updated object. - **New deployment URL:** Trigger a deployment and confirm the generated URL uses the new name. - **Auth flow:** If the project uses an OAuth provider, complete a sign-in end-to-end, since callback mismatches surface here. - **Environment variables:** Search Settings, then Environment Variables, for the old name and confirm no stale values remain. - **CI/CD pipeline:** Trigger a run. A failed deploy here usually means the pipeline resolves the project by name instead of by `VERCEL_PROJECT_ID`; switch it to the ID. Once these checks pass, the rename is complete and safe to build on. ## Next steps With the rename done and the four categories updated, your project is ready to keep building on. [Start a new Vercel project](https://vercel.com/new) or [browse the templates](https://vercel.com/templates) for a framework-ready starting point. ## Related resources - [General settings](https://vercel.com/docs/project-configuration/general-settings) - [Vercel CLI project reference](https://vercel.com/docs/cli/project) - [Update a project](https://vercel.com/docs/rest-api/reference/endpoints/projects/update-an-existing-project) - [Linking projects with CLI](https://vercel.com/docs/cli/project-linking) - [Generated deployment URLs](https://vercel.com/docs/deployments/generated-urls) ## Frequently asked questions ### Does renaming a Vercel project break Git auto-deploys? No. Git integrations and auto-deploys run on the immutable project ID, not the name, so pushes to your connected repository keep triggering deployments exactly as before. The same applies to CI/CD pipelines that use the `VERCEL_PROJECT_ID` secret. Only stored copies of the old name, such as URLs in environment variables, need updating. ### Will old \*.vercel.app URLs still work after I rename a project? Vercel doesn't guarantee it. New deployments generate URLs with the new name in the `-.vercel.app` format, but pre-rename generated URLs aren't guaranteed to stay accessible. Replace any old URL that's bookmarked, shared, or stored externally, and use a custom domain for production traffic. ### What's the difference between renaming and transferring a Vercel project? A rename changes the display name within the same team or account, and ownership stays put. A [transfer](https://vercel.com/docs/projects/managing-projects) moves the project, including its deployments, environment variables, domains, and aliases, to a different team or account. Use rename for a label change and transfer when the project needs a new owner. ### Are there characters I can't use in a Vercel project name? Project names must be lowercase and no longer than 100 characters. They can contain letters, digits, and the characters `.`, `_`, and `-`, but not the sequence `---`. If the name field rejects your entry, an uppercase letter or an unsupported character is the usual cause.