---
title: How do I migrate away from `vercel.json` env and build.env?
description: Information on how to migrate your `vercel.json` environment variables to the Environment Variables UI.
url: /kb/guide/how-do-i-migrate-away-from-vercel-json-env-and-build-env
canonical_url: "https://vercel.com/kb/guide/how-do-i-migrate-away-from-vercel-json-env-and-build-env"
published: 2025-11-03
last_updated: 2026-07-16
authors: Sam Ko
related:
  - /docs/environment-variables
  - /docs/configuration
  - /docs/platform/projects
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Transferring a project](https://vercel.com/docs/projects/transferring-projects?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Learn how to transfer a project between Vercel teams.
- [Managing environment variables](https://vercel.com/docs/environment-variables/managing-environment-variables?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Learn how to create and manage environment variables for Vercel.
- [Managing environment variables across environments](https://vercel.com/docs/environment-variables/manage-across-environments?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Add, sync, and verify environment variables across development, preview, production, and custom environments using the C
- [Environment Variables UI](https://vercel.com/blog/environment-variables-ui?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related)
- [Shared environment variables](https://vercel.com/docs/environment-variables/shared-environment-variables?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Learn how to use Shared environment variables, which are environment variables that you define at the Team level and can
- [Sensitive environment variables](https://vercel.com/docs/environment-variables/sensitive-environment-variables?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Environment variables that cannot be decrypted once created.
- [How to add and manage environment variables on Vercel](https://vercel.com/kb/guide/how-to-add-vercel-environment-variables?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Add environment variables to Vercel through the dashboard, CLI, or REST API, scope them to each environment, and pull th
- [How do I set up a staging environment on Vercel?](https://vercel.com/kb/guide/set-up-a-staging-environment-on-vercel?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Information on how to set up a staging environment on Vercel.
- [How do I resolve a 'process.env.CI = true' error?](https://vercel.com/kb/guide/how-do-i-resolve-a-process-env-ci-true-error?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Information on resolving a 'process.env.CI = true' error.
- [How can I use AWS SDK Environment Variables on Vercel?](https://vercel.com/kb/guide/how-can-i-use-aws-sdk-environment-variables-on-vercel?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — How to use AWS SDK Environment Variables on Vercel
- [Migrate a Next.js app from Webflow Cloud to Vercel](https://vercel.com/kb/guide/migrate-a-next-js-app-from-webflow-cloud-to-vercel?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=related) — Move your Next.js app from Webflow Cloud to Vercel: remove the OpenNext Cloudflare adapter, drop the base path, map stor

Full cross-link map for this page: [/kb/guide/how-do-i-migrate-away-from-vercel-json-env-and-build-env.graph.md](/kb/guide/how-do-i-migrate-away-from-vercel-json-env-and-build-env.graph.md?from=related&source_path=%2Fkb%2Fguide%2Fhow-do-i-migrate-away-from-vercel-json-env-and-build-env&source_site=vercel-kb&relationship=graph)
<!-- /docsgraph:related -->


This article will help you migrate your `vercel.json` environment variables (legacy method) to the [Environment Variables UI](https://vercel.com/docs/environment-variables).

## Migrate Your Environment Variables

You may have configured the [`env`](https://vercel.com/docs/configuration#project/env) and [`build.env`](https://vercel.com/docs/configuration#project/build-env) legacy properties in a `vercel.json` file:

```json
{
  "env": {
    "MY_KEY": "this is the value",
    "SECRET": "@my-secret-name"
  },
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}
```

We **no longer** recommend you use this legacy method for environment variables. Instead, we recommend you migrate your environment variables to the [Environment Variables UI](https://vercel.com/docs/environment-variables). Here is how to add the same envrionment variables setup to our Environment Variables UI using the example above:

Migrating to the Environment Variables UI will help you avoid errors when implementing your environment variables.

## Redeploy

Once you have successfully moved your environment variables to the [Environment Variables UI](https://vercel.com/docs/environment-variables), make sure to redeploy your [Vercel Project](https://vercel.com/docs/platform/projects) to reflect these new changes.