--- description: Configuring environment variables and secrets for local development title: Environment variables and secrets image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt > Use this file to discover all available pages before exploring further. # Environment variables and secrets Last updated Sep 3, 2026|Copy as Markdown| [View as Markdown](https://641a99ee.previews.developers.cloudflare.com/workers/local-development/environment-variables/index.md)| [Agent setup](https://641a99ee.previews.developers.cloudflare.com/agent-setup/) Caution Do not use `vars` to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead. Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the same directory as the Wrangler configuration file. Note You can use the [`secrets` configuration property](https://641a99ee.previews.developers.cloudflare.com/workers/wrangler/configuration/#secrets-configuration-property) to declare which secret names your Worker requires. When defined, only the keys listed in `secrets.required` are loaded from `.dev.vars` or `.env`. Additional keys are excluded and missing keys produce a warning. Note Choose to use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will not be included in the `env` object during local development. These files should be formatted using the [dotenv ↗](https://hexdocs.pm/dotenvy/dotenv-file-format.html) syntax. For example: *.dev.vars / .envbash* ```bash SECRET_KEY="value" API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` Do not commit secrets to git The `.dev.vars` and `.env` files should not be committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. To set different secrets for each Cloudflare environment, create files named `.dev.vars.` or `.env.`. When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic `.dev.vars` (or `.env`) file. - When using `.dev.vars.` files, all secrets must be defined per environment. If `.dev.vars.` exists then only this will be loaded; the `.dev.vars` file will not be loaded. - In contrast, all matching `.env` files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence: - `.env..local` (most specific) - `.env.local` - `.env.` - `.env` (least specific) Controlling \`.env\` handling It is possible to control how `.env` files are loaded in local development by setting environment variables on the process running the tools. - To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. - To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. This is not needed when using the [`secrets` configuration property](https://641a99ee.previews.developers.cloudflare.com/workers/wrangler/configuration/#secrets-configuration-property), which loads from `process.env` automatically. ### Basic setup Here are steps to set up environment variables for local development using either `.dev.vars` or `.env` files. 1. Create a `.dev.vars` / `.env` file in your project root. 2. Add key-value pairs: *.dev.vars/.envini* ```ini API_HOST="localhost:3000" DEBUG="true" SECRET_TOKEN="my-local-secret-token" ``` 3. Run your `dev` command **Wrangler**npmyarnpnpm ``` npx wrangler dev ``` ``` yarn wrangler dev ``` ``` pnpm wrangler dev ``` **Vite plugin**npmyarnpnpm ``` npx vite dev ``` ``` yarn vite dev ``` ``` pnpm vite dev ``` ## Multiple local environments To simulate different local environments, you can provide environment-specific files. For example, you might have a `staging` environment that requires different settings than your development environment. 1. Create a file named `.dev.vars.`/ `.env.`. For example, we can use `.dev.vars.staging`/ `.env.staging`. 2. Add key-value pairs: *.dev.vars.staging/.env.stagingini* ```ini API_HOST="staging.localhost:3000" DEBUG="false" SECRET_TOKEN="staging-token" ``` 3. Specify the environment when running the `dev` command: **Wrangler**npmyarnpnpm ``` npx wrangler dev --env staging ``` ``` yarn wrangler dev --env staging ``` ``` pnpm wrangler dev --env staging ``` **Vite plugin**npmyarnpnpm ``` CLOUDFLARE_ENV=staging npx vite dev ``` ``` CLOUDFLARE_ENV=staging yarn vite dev ``` ``` CLOUDFLARE_ENV=staging pnpm vite dev ``` - If using `.dev.vars.staging`, only the values from that file will be applied instead of `.dev.vars`. - If using `.env.staging`, the values will be merged with `.env` files, with the most specific file taking precedence. ## Learn more - To learn how to configure multiple environments in Wrangler configuration, [read the documentation](https://641a99ee.previews.developers.cloudflare.com/workers/wrangler/environments/#_top). - To learn how to use Wrangler environments and Vite environments together, [read the Vite plugin documentation](https://641a99ee.previews.developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/) Was this helpful? YesNo ## On this page [![](https://641a99ee.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://641a99ee.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"WebPage","@id":"https://developers.cloudflare.com/workers/local-development/environment-variables/#page","headline":"Environment variables and secrets · Cloudflare Workers docs","description":"Configuring environment variables and secrets for local development","url":"https://developers.cloudflare.com/workers/local-development/environment-variables/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-03","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```