--- title: Environment Variables description: Manage environment variables for your Headless Platform environments url: https://developers.wpengine.com/docs/headless-platform/platform-guides/environment-variables/ image: https://developers.wpengine.com/og/docs/headless-platform/platform-guides/environment-variables.png --- # Environment Variables Environment variables are composed of key-value pairs set externally from your source code. They can influence the behavior of the web application, providing a way to adjust its configuration without changing the codebase. Each value can be modified based on the specific Headless Platform environment. Modifications to environment variables do not retroactively affect past builds. They are effective only for subsequent builds. ## Managing environment variables To add new variables either visit the Headless Platform Environment Details page and click the `Go to variables` link of the `Variables` card (first image) or select the left-hand submenu `Variables` item (second image). ![Visit env vars screen](https://developers.wpengine.com/_astro/manage-variables.vuR7V8i2_Z1x8xJV.webp) ![SubMenu Variables Item](https://developers.wpengine.com/_astro/open-variables-from-submenu.D288MmQy_Z2eYEc0.webp) On first entry to this page you will see an empty Environment Variables table in the non-edit mode. To add a row select the `Add environment variable` button. ![Add environment variable](https://developers.wpengine.com/_astro/add-environment-variable.C0VJiuEW_Z9WoR8.webp) Enter a key and value for each of your variable rows. To add further rows, while in edit mode, press `Add Variable` and input additional key-value pairs. Then click `Save changes` to confirm. ![Add new variable](https://developers.wpengine.com/_astro/add-new-variable-and-save.DK6MJicz_Z2dllvU.webp) Upon saving the table your changes are persisted but not yet in use, so you will be prompted to redeploy the Environment with the latest variables. This is optional but if you redeploy you will be taken to the Environment Details page & a redeploy will commence. ![Rebuild site](https://developers.wpengine.com/_astro/rebuild-site.52hLpZ53_Z1J3ygW.webp) After saving, your environment variables will be displayed in the table. To edit them again, just click the Add environment variable button. You’ll be asked whether to redeploy each time you save. ![Add additional variables](https://developers.wpengine.com/_astro/additional-variables.0ouwcslO_2jbYtr.webp) You can download your existing environment variables list when not in edit mode. This is done via the download icon, below the `Add environment Variable` button. ![Download variables](https://developers.wpengine.com/_astro/download-variables.HHtwql7Z_Z2mywUw.webp) This presents you with a popup modal with 2 options for download format: `CSV` & `.env`. ![Download variables modal](https://developers.wpengine.com/_astro/download-var-modal.BG-wl8CV_Z1eyb8v.webp) To upload your downloaded environment file, simply click the bulk upload button. The file should be in .env format. ![Upload variables button](https://developers.wpengine.com/_astro/upload-variables-button.CnQdr8zZ_TBFVz.webp) This presents you with a pop-up modal, offering options to upload files from your computer or via drag-and-drop. ![Upload variables modal](https://developers.wpengine.com/_astro/upload-env-variables-modal.1dyOjEOU_11qBgx.webp) To modify existing variables, click the edit icon located below the Add environment variable button. Once in edit mode, you can modify or delete individual rows. You will also see a quick Add variable button for adding new entries. ![Edit variable](https://developers.wpengine.com/_astro/edit-variable.CkIAw9_G_7XjO5.webp) You can remove a variable by clicking on the trash icon while in edit mode. ![Delete variable](https://developers.wpengine.com/_astro/delete-variable.CfyuaAsa_2q4RA3.webp) > **Note** > > You will need to rebuild your application to apply any changes you make to the environment variables using this process. ## Limitations ### Reserved variables and namespaces Our Headless Platform reserves some environment variables and prefixes. You cannot use these for your own variables: - `PORT` - `WPE_` prefix - `HEADLESS_METADATA` prefix If you try to use these reserved keys, our Headless Platform will display a warning and won’t save the variable. ### Allowed format of keys Environment variables’ keys on our Headless Platform must match the following regex: `[a-zA-Z_]{1,}[a-zA-Z0-9_]*`. ### Special environment variables The table below lists the environment variables for customizing operations: | Environment Variable | Description | Example | | ----------------------- | -------------------------------------------------------------------------------------------------- | ------- | | `HEADLESS_NO_PURGE_CDN` | Omit purging the CDN cache after deployments. Note: this may impact your site’s content freshness. | `true` | ## System environment variables Our Headless Platform automatically generates a collection of environment variables to provide users with metadata about their environments. This includes variables such as the Build ID or a flag that signifies whether the environment in question is a preview or production environment. You can find the complete list of system environment variables in the table below: | Environment Variable | Description | Example | | ------------------------------- | -------------------------------------------------------------------------- | -------------------------------------- | | `CI` | Present during the build step. | `true` | | `HEADLESS_METADATA` | Indicates that system environment variables are added to your deployments. | `true` | | `HEADLESS_METADATA_SOURCE` | Source control provider | `github` | | `HEADLESS_METADATA_REPOSITORY` | Git repository name and owner | `some-user/repo-name` | | `HEADLESS_METADATA_APP_NAME` | Name of the Headless Platform application | `my-app` | | `HEADLESS_METADATA_ENV_NAME` | Name of the Headless Platform environment | `main-env` | | `HEADLESS_METADATA_COMMIT_SHA` | Commit identifier for the current build | `4e6f58b` | | `HEADLESS_METADATA_ENV_BRANCH` | Git branch used for the current build | `main` | | `HEADLESS_METADATA_PREVIEW_ENV` | Flag that indicates if the environment is a ‘preview’ type | `true` | | `HEADLESS_METADATA_ENV_ID` | Unique identifier for the Headless Platform environment | `026bbe63-8043-1c3e-00e5-d95c5a12aa32` | | `HEADLESS_METADATA_BUILD_ID` | Identifier for the latest build | `5f42ce7c-b894-887d-1b9e-69d2429acbdd` | | `HEADLESS_METADATA_CLEAN_BUILD` | Indicates if the build is a ‘clean’ build | `false` | ## Was this helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```