---
title: Define Environment Variables
description: Learn how to set and use environment variables in Nx projects, including file-based configuration, custom env files, and ad-hoc variable definition across different operating systems.
filter: 'type:Guides'
---

Environment variables are global system variables accessible by all the processes running under the Operating System (OS).
Environment variables are useful to store system-wide values such as the directories to search for executable programs
(PATH), OS version, Network Information, and custom variables. These env variables are passed at build time and used at
the runtime of an app.

## Set environment variables

By default, Nx will load any environment variables you place in the following files:

1. `[project-root]/.env.[target-name].[target-configuration-name].local`
2. `[project-root]/.env.[target-name].[target-configuration-name]`
3. `[project-root]/.[target-name].[target-configuration-name].local.env`
4. `[project-root]/.[target-name].[target-configuration-name].env`
5. `[project-root]/.env.[target-configuration-name].local`
6. `[project-root]/.env.[target-configuration-name]`
7. `[project-root]/.[target-configuration-name.local.env`
8. `[project-root]/.[target-configuration-name].env`
9. `[project-root]/.env.[target-name].local`
10. `[project-root]/.env.[target-name]`
11. `[project-root]/.[target-name].local.env`
12. `[project-root]/.[target-name].env`
13. `[project-root]/.env.local`
14. `[project-root]/.local.env`
15. `[project-root]/.env`
16. `.env.[target-name].[target-configuration-name].local`
17. `.env.[target-name].[target-configuration-name]`
18. `.[target-name].[target-configuration-name].local.env`
19. `.[target-name].[target-configuration-name].env`
20. `.env.[target-configuration-name].local`
21. `.env.[target-configuration-name]`
22. `.[target-configuration-name].local.env`
23. `.[target-configuration-name].env`
24. `.env.[target-name].local`
25. `.env.[target-name]`
26. `.[target-name].local.env`
27. `.[target-name].env`
28. `.env.local`
29. `.local.env`
30. `.env`

Or shorter we will use the following order:

- [project-root]/[target-name].[target-configuration-name]
- [project-root]/[target-configuration-name]
- [project-root]/[target-name]
- [project-root]/{general environment variables}
- [target-name].[target-configuration-name]
- [target-configuration-name]
- [target-name]
- {general environment variables}

{% aside type="caution" title="Order is important" %}
Nx will move through the above list, ignoring files it can't find, and loading environment variables
into the current process for the ones it can find. If it finds a variable that has already been loaded into the process,
it will ignore it. It does this for two reasons:

1. Developers can't accidentally overwrite important system level variables (like `NODE_ENV`)
2. Allows developers to create `.env.local` or `.local.env` files for their local environment and override any project
   defaults set in `.env`
3. Allows developers to create target specific `.env.[target-name]` or `.[target-name].env` to overwrite environment variables for specific targets. For instance, you could increase the memory use for node processes only for build targets by setting `NODE_OPTIONS=--max-old-space-size=4096` in `.build.env`

For example:

1. `apps/my-app/.env.local` contains `NX_PUBLIC_API_URL=http://localhost:3333`
2. `apps/my-app/.env` contains `NX_PUBLIC_API_URL=https://api.example.com`
3. Nx will first load the variables from `apps/my-app/.env.local` into the process. When it tries to load the variables
   from `apps/my-app/.env`, it will notice that `NX_PUBLIC_API_URL` already exists, so it will ignore it.

We recommend nesting your **app** specific `env` files in `apps/your-app`, and creating workspace/root level `env` files
for workspace-specific settings (like the [Nx Cloud token](/docs/guides/nx-cloud/access-tokens)).
{% /aside %}

{% aside type="caution" title="Env files are not loaded in batch mode" %}
The task-specific `.env` files described above are **not** loaded for tasks run with [batch mode](/docs/reference/glossary#batch-mode) (Gradle and Maven tasks run this way be default). Batch processes only receive the variables present in the current environment and root .env files, like `.env` and `.env.local`, so variables defined in files like `.env.[target-name]` won't be available.
{% /aside %}

### Environment variables for atomized targets

Atomized targets have their names created dynamically, typically using the file names as a suffix. This makes it difficult to define environment variable files for them.
For atomized targets, Nx will instead search for atomized target's parent and non-atomized target.

Instead of looking for a file named e.g. `.env.e2e-ci--path/to/atomized/file`, Nx will instead look for:

- `.env.e2e-ci` and
- `.env.e2e`

The above order with combinations of targets, configurations and path priority remainst the same:

- [project-root]/[parent-target-name].[target-configuration-name]
- [project-root]/[non-atomized-target-name].[target-configuration-name]
- [project-root]/[target-configuration-name]
- [project-root]/[parent-target-name]
- [project-root]/[non-atomized-target-name]
- [project-root]/{general environment variables}
- [target-name].[target-configuration-name]
- [target-configuration-name]
- [parent-target-name]
- [non-atomized-target-name]
- {general environment variables}

### Environment variables for configurations

Nx will only load environment variable files for a particular configuration if that configuration is defined for a task, even if you specify that configuration name from the command line. So if there is no `development` configuration defined for the `app`'s `build` task, the following command will use `.env.build` instead of `.env.build.development`:

```shell
nx build app --configuration development
```

In order to have Nx actually use the `.env.build.development` environment variables, the `development` configuration needs to be set for the task (even if it is empty).

```jsonc {% meta="{5-7}" %}
// apps/app/project.json
{
  "targets": {
    "build": {
      // ...
      "configurations": {
        "development": {},
      },
    },
  },
}
```

### Point to custom env files

If you want to load variables from `env` files other than the ones listed above:

1. Use the [env-cmd](https://www.npmjs.com/package/env-cmd) package: `env-cmd -f .qa.env nx serve`
2. Use [dotenvx](https://github.com/dotenvx/dotenvx): `dotenvx run --env-file=.qa.env -- nx serve`
3. Use the `envFile` option of the [run-commands](/docs/guides/tasks--caching/run-commands-executor#envfile) builder and execute your command inside of the builder

### Ad-hoc variables

You can also define environment variables in an ad-hoc manner using support from your OS and shell.

**Unix systems**

In Unix systems, we need to set the environment variables before calling a command.

Let's say that we want to define an API URL for the application to use:

```shell
NX_PUBLIC_API_URL=http://localhost:3333 nx build myapp
```

**Windows (cmd.exe)**

```shell
set "NX_PUBLIC_API_URL=http://localhost:3333" && nx build myapp
```

**Windows (Powershell)**

```shell
($env:NX_PUBLIC_API_URL = "http://localhost:3333") -and (nx build myapp)
```