How do I change the name of my Vercel Project?

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.

Copy link to headingHow 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.

Copy link to headingRename from the dashboard

For a one-off rename while you're signed in, use the dashboard:

1. Open your project in the Vercel 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 for the full constraints.

Copy link to headingRename with the Vercel CLI

For terminal workflows and scripts, rename with the Vercel CLI:

vercel project rename <current-name> <new-name>

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.

Copy link to headingRename with the REST API

For programmatic renames across many projects, call the update-project endpoint:

curl -X PATCH "<https://api.vercel.com/v9/projects/{idOrName}>" \
  -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.

Copy link to headingWhy 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.

Copy link to headingWhat 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:

New deployments generate URLs in the <project-name>-<scope-slug>.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.

Copy link to headingHow 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/<new-name> 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.

Copy link to headingNext steps

With the rename done and the four categories updated, your project is ready to keep building on. Start a new Vercel project or browse the templates for a framework-ready starting point.

Copy link to headingRelated resources

• General settings
• Vercel CLI project reference
• Update a project
• Linking projects with CLI
• Generated deployment URLs

Copy link to headingFrequently asked questions

Copy link to headingDoes 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.

Copy link to headingWill 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 <project-name>-<scope-slug>.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.

Copy link to headingWhat'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 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.

Copy link to headingAre 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.