--- title: Nx Environment Variables description: Learn how Nx loads environment variables and find a reference for the variables that configure Nx, plugins, and Nx Cloud. sidebar: order: 6 filter: 'type:References' --- Nx loads environment variables from the process and from environment files in your workspace. You can use environment variables to configure task behavior, pass values to applications, and change how Nx operates. Frameworks and bundlers can have additional rules for exposing environment variables to application code. Refer to their documentation for those rules. ## Loading environment variables Nx loads environment variables from the following files, in order: 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` Nx checks environment files using these priorities: - Project-specific files before workspace-level files - Target and configuration-specific files before general files - Local files before non-local files {% aside type="caution" title="Order is important" %} Nx moves through the list, ignores files it cannot find, and loads environment variables into the current process. If a variable is already loaded, Nx does not overwrite it. This behavior: 1. Prevents developers from accidentally overwriting important system-level variables such as `NODE_ENV`. 2. Allows `.env.local` or `.local.env` files to override project defaults in `.env`. 3. Allows target-specific files such as `.env.build` or `.build.env` to override variables for a particular target. 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 loads the value from `apps/my-app/.env.local` first. Because `NX_PUBLIC_API_URL` is already set when Nx reads `apps/my-app/.env`, Nx ignores the second value. Store application-specific environment files in the application directory, such as `apps/my-app`. Use workspace-level environment files for workspace-wide settings, such as the [Nx Cloud access token](/docs/kb/access-tokens). {% /aside %} {% aside type="caution" title="Package managers can set variables before Nx runs" %} A package manager can add variables to the process before Nx reads environment files. Nx preserves those values because they are already set. For example, the npm `node-options` setting from a project, user, or global `.npmrc` becomes a `NODE_OPTIONS` environment variable when you run `npm run nx ...` or `npx nx ...`. If `.env` also defines `NODE_OPTIONS`, the `.npmrc` value takes precedence. Running `nx` directly uses the value from `.env`. If you rely on a variable from an environment file, make sure nothing else sets it first. {% /aside %} {% aside type="caution" title="Task-specific environment files are not loaded in batch mode" %} Nx does not load task-specific environment files for tasks run in [batch mode](/docs/reference/glossary#batch-mode). Gradle and Maven tasks run in batch mode by default. Batch processes receive variables from the current environment and root environment files such as `.env` and `.env.local`. Variables in files such as `.env.[target-name]` are not available. {% /aside %} ### Environment variables for atomized targets Atomized target names are created dynamically, typically by using file names as suffixes. Because those names are difficult to use in environment file names, Nx searches for the atomized target's parent and non-atomized target instead. For example, instead of looking for `.env.e2e-ci--path/to/atomized/file`, Nx looks for: - `.env.e2e-ci` - `.env.e2e` The combinations of targets, configurations, and path priorities follow this order: - `[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 only loads environment files for a configuration when that configuration is defined for the task. If the `build` target for `app` does not define a `development` configuration, the following command uses `.env.build` instead of `.env.build.development`: ```shell nx build app --configuration development ``` To load `.env.build.development`, define the `development` configuration for the task, even if the configuration is empty: ```jsonc {% meta="{5-7}" %} // apps/app/project.json { "targets": { "build": { // ... "configurations": { "development": {}, }, }, }, } ``` ### Load a custom environment file To load variables from an environment file that is not listed above, use one of the following options: 1. Use [env-cmd](https://www.npmjs.com/package/env-cmd): `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 executor](/docs/reference/nx/executors#envfile) ### Ad-hoc environment variables You can also set environment variables for an individual command by using your operating system and shell. **Unix systems** Set the environment variable before the command: ```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) ``` ## Nx environment variables The following environment variables are ones that you can set to change the behavior of Nx in different environments. Everyday settings are listed under **Common**. Settings for debugging, internals, and specialized tooling are under **Advanced**. ### Common | Property | Type | Description | | ----------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_BAIL` | boolean | If set to `true`, Nx will stop command execution after the first failed task. Can be overridden on the command line with `--nxBail`. | | `NX_BASE` | string | The default base branch to use when calculating the affected projects. Can be overridden on the command line with `--base`. | | `NX_BATCH_MODE` | boolean | If set to `true`, Nx will run task(s) in batches for executors which support batches. | | `NX_CACHE_DIRECTORY` | string | The cache for task outputs is stored in a shared `~/.nx//cache` directory by default, where the id identifies the workspace. Set this variable to use a different directory. | | `NX_CACHE_FAILURES` | boolean | If set to `true`, Nx caches failing tasks in addition to successful ones. | | `NX_DAEMON` | boolean | If set to `false`, disables the Nx daemon process. Disable the daemon to print `console.log` statements in plugin code you are developing. | | `NX_DEFAULT_OUTPUT_STYLE` | string | The default output style to use when running tasks. Can be overridden on the command line with `--outputStyle`. | | `NX_DEFAULT_PROJECT` | string | The default project used for commands which require a project. e.g. `nx build`, `nx g component`, etc. | | `NX_DISABLE_NX_CACHE` | boolean | Rerun the tasks even when the results are available in the cache. | | `NX_DISABLE_REMOTE_CACHE` | boolean | Disable all remote caching features. This means that the remote cache will not be read from or written to. Includes Nx Cloud and self-hosted caches. | | `NX_DRY_RUN` | boolean | If set to `true`, will perform a dry run of the generator. No files will be created and no packages will be installed. | | `NX_HEAD` | string | The default head branch to use when calculating the affected projects. Can be overridden on the command line with `--head`. | | `NX_IGNORE_CYCLES` | boolean | If set to `true`, Nx will ignore errors created by a task graph circular dependency. Can be overridden on the command line with `--nxIgnoreCycles` | | `NX_INTERACTIVE` | boolean | If set to `true`, will allow Nx to prompt you in the terminal to answer some further questions when running generators. | | `NX_LEGACY_AFFECTED` | boolean | If set to `false`, `nx affected` selects the individual tasks whose inputs a change reaches, rather than whole projects. | | `NX_LOAD_DOT_ENV_FILES` | boolean | If set to 'false', Nx will not load any environment files (e.g. `.local.env`, `.env.local`) | | `NX_MAX_CACHE_SIZE` | string | Alternative to configuring `maxCacheSize` in `nx.json`. Defines the maximum size of the local task cache. See [`maxCacheSize`](/docs/reference/nx-json#max-cache-size) for supported units and behavior details. | | `NX_MAX_MESSAGE_SIZE` | number | Maximum size, in bytes, of a single message on an Nx socket (daemon, plugin worker, and forked process). Defaults to 2147483648 (2 GiB). A peer that declares a larger message is refused before the payload is buffered. Set to 0 to remove the limit. The daemon reads it at startup, so run `nx reset` after changing it. | | `NX_MIGRATE_CLI_VERSION` | string | The version of Nx to use for running the `nx migrate` command. If not set, it defaults to `latest`. | | `NX_MIGRATE_SKIP_INSTALL` | boolean | If set to `true`, `nx migrate --run-migrations` will not automatically perform the installation of the packages. | | `NX_MIGRATE_USE_LOCAL` | boolean | If set to `true`, will use the locally installed version of `nx` instead of downloading the latest version to run the `nx migrate` command. | | `NX_MULTI_MAJOR_MODE` | string | How `nx migrate` handles a jump across majors. `direct` goes straight to the target, `gradual` goes to the smallest recommended step. Overrides [`migrate.multiMajorMode`](/docs/reference/nx-json#migrate). | | `NX_PARALLEL` | number | The number of tasks Nx should run in parallel. Overrides any configured value inside nx.json | | `NX_SKIP_NX_CACHE` | boolean | Rerun the tasks even when the results are available in the cache. | | `NX_SKIP_REMOTE_CACHE` | boolean | Disable all remote caching features. This means that the remote cache will not be read from or written to. Includes Nx Cloud and self-hosted caches. | | `NX_TUI` | boolean | If set to `true` or `false`, will enable or disable the Terminal UI (TUI) for running tasks. TUI provides an interactive visual interface for task execution | | `NX_TUI_AUTO_EXIT` | boolean/number | Controls whether the TUI automatically exits after tasks finish. If `true`, exits immediately. If `false`, never exits automatically. If a number, shows a countdown for that many seconds before exiting | | `NX_USE_LOCAL` | boolean | If set to `true`, Nx will use the locally installed version instead of downloading the latest version from npm for commands like `nx init` and `nx migrate`. | | `NX_VERBOSE_LOGGING` | boolean | If set to `true`, will print debug information useful for troubleshooting | | `NX_WORKSPACE_DATA_DIRECTORY` | string | The project graph database is stored in a shared `~/.nx//databases` directory by default, where the id identifies the workspace. This checkout's own `.nx/workspace-data` holds its daemon logs, file map and source maps. Set this variable to put all of them in the directory you name, which also opts the cache out of its shared location. | ### Advanced | Property | Type | Description | | ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_ADD_PLUGINS` | boolean | If set to `false`, Nx will not add plugins to infer tasks. This is `true` by default. | | `NX_CACHE_PROJECT_GRAPH` | boolean | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph. | | `NX_COMPILE_CACHE` | boolean | If set to `false`, disables Node's built-in V8 bytecode compile cache for Nx processes (CLI, daemon, plugin workers). The cache is enabled by default on Node 22.8+ and speeds up repeated invocations by reusing compiled bytecode. Has no effect on older Node versions. | | `NX_COMPLETE` | string | Internal. Set by the shell completion wrapper scripts (generated by `nx completion `) to put Nx in tab-completion mode. The value is the shell name (`bash`, `zsh`, `fish`, or `powershell`). Do not set this manually. | | `NX_DAEMON_SOCKET_DIR` | string | Alias of `NX_SOCKET_DIR`, used only when `NX_SOCKET_DIR` is not set. Despite the name, it controls all Nx socket placements, not just the daemon socket. Prefer `NX_SOCKET_DIR` in new setups. | | `NX_FORCE_REUSE_CACHED_GRAPH` | boolean | If set to `true`, Nx will reuse an existing cached project graph when available and skip recomputing it. Useful in short-lived CI steps that run immediately after a step which already computed the graph. | | `NX_FORMAT_SORT_TSCONFIG_PATHS` | boolean | If set to `true`, generators will sort the TypeScript path mappings in the root tsconfig file. | | `NX_GENERATE_QUIET` | boolean | If set to `true`, will prevent Nx logging file operations during generate | | `NX_IGNORE_UNSUPPORTED_TS_SETUP` | boolean | If set to `true`, generators continue when a plugin does not support the workspace's TypeScript project references setup. Use this escape hatch only if you understand the compatibility risk. | | `NX_INVOCATION_ROOT_PID` | number | Internal. Set by Nx to the PID of the root Nx process. Used to detect recursive task invocation loops across nested Nx processes. Do not set this manually. | | `NX_ISOLATE_PLUGINS` | boolean | Forces plugin isolation on or off, overriding the automatic detection. Set to `true` to always run inference plugins in isolated workers, or `false` to always run them in-process. | | `NX_MIGRATE_INSTALL_CONCURRENCY` | number | Limits the number of concurrent package installs when fetching migration metadata. Useful for avoiding package manager cache conflicts on Windows with private registries. If not set, installs run with no concurrency limit. | | `NX_MIGRATE_SKIP_REGISTRY_FETCH` | boolean | **Deprecated, will be removed in Nx 24** - use `NX_MIGRATE_USE_REGISTRY_RESOLUTION` (set to `false`) instead. If set to `true`, will skip fetching metadata from the registry and instead use the installation method directly. Legacy alias for setting `NX_MIGRATE_USE_REGISTRY_RESOLUTION` to `false`; the newer variable takes precedence when both are set. | | `NX_MIGRATE_USE_REGISTRY_RESOLUTION` | boolean | Whether `nx migrate` resolves package versions and migration metadata via the npm registry (faster) instead of a package-manager install. Set to `false` to always resolve through your package manager. Takes precedence over the legacy `NX_MIGRATE_SKIP_REGISTRY_FETCH` variable and the `migrate.useRegistryResolution` setting in `nx.json`. Defaults to `true`. | | `NX_NATIVE_COMMAND_RUNNER` | boolean | If set to `false`, disables the native pseudo-terminal command runner and falls back to the standard Node.js child process. Enabled by default. | | `NX_NATIVE_FILE_CACHE_DIRECTORY` | string | The cache for native `.node` files is stored under a per-user temp directory by default. Set this variable to use a different directory, interpreted as an absolute path. It has to be a directory only your user can reach, since Nx loads a native binding out of it; Nx skips the cache and loads the binding in place if it isn't. | | `NX_NATIVE_FILE_LOGGING` | string | Enables the native (Rust) tracing logger and writes logs to `.nx/workspace-data/nx.log`. Accepts the same filter directives as `NX_NATIVE_LOGGING` (e.g. `debug`, `info`, `[{project_name=myapp}]`). Useful for debugging native code paths. | | `NX_NATIVE_LOGGING` | string | Filter directive for the native (Rust) tracing logger. Defaults to `nx::native=info`. Set to a log level (`trace`, `debug`, `info`, `warn`, `error`, `off`) to control all native logs, or scope by crate or module (e.g. `nx=trace`, `nx::native::tasks::hashers=debug`, `[{project_name=myapp}]`). | | `NX_PERF_LOGGING` | boolean | If set to `true`, will print debug information useful for profiling executors and Nx itself | | `NX_PLUGIN_NO_TIMEOUTS` | boolean | If set to `true`, plugin operations will not timeout | | `NX_PREFER_NODE_STRIP_TYPES` | boolean | When the Node.js runtime exposes native TypeScript stripping (`process.features.typescript` - Node 23.6+ unflagged, 22.18+ LTS unflagged, or 22.6+ with `--experimental-strip-types`), Nx loads TypeScript configuration files via Node directly (faster, no `@swc-node/register`/`ts-node` registration). Set to `false` to opt out and force `@swc-node/register` or `ts-node`. When native stripping fails on an unsupported construct (e.g. `enum`, runtime `namespace`), Nx falls back to `@swc-node/register`/`ts-node` + `tsconfig-paths` automatically; set `NX_VERBOSE_LOGGING=true` to see when fallback triggers. | | `NX_DISABLE_TSCONFIG_PATHS` | boolean | Skip `tsconfig-paths` registration on the `@swc-node/register`/`ts-node` fallback path. Set to `true` when relying on package manager workspaces (pnpm/yarn/npm) for project linking and `tsconfig` path aliases aren't needed. | | `NX_ENABLE_TS_SYNC_TRANSITIVE_DEPENDENCIES` | boolean | If set to `true`, `nx sync` adds TypeScript project references for transitive dependencies in addition to direct dependencies. | | `NX_PREFER_TS_NODE` | boolean | If set to `true`, Nx will use `ts-node` for local execution of plugins even if `@swc-node/register` is installed. | | `NX_PROCESS_KILL_GRACE_PERIOD` | number | Time in milliseconds to wait for child processes to exit gracefully before force-killing them. Defaults to `5000`. | | `NX_PROFILE` | string | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/docs/kb/performance-profiling) to visualize the performance of Nx across multiple processes. | | `NX_PROJECT_GRAPH_CACHE_DIRECTORY` | string | Alias of `NX_WORKSPACE_DATA_DIRECTORY`, used only when `NX_WORKSPACE_DATA_DIRECTORY` is not set. Prefer `NX_WORKSPACE_DATA_DIRECTORY` in new setups. | | `NX_REJECT_UNKNOWN_LOCAL_CACHE` | boolean | Legacy cache safety toggle. Set to `0` or `false` to allow reading a local cache that wasn't populated by the current machine. Not supported with the new database cache. See [legacy cache](/docs/reference/deprecated/legacy-cache#nxrejectunknownlocalcache). | | `NX_RUNNER` | string | No longer read by Nx. Use `NX_TASKS_RUNNER` instead. | | `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN` | string | Bearer token passed as the `Authorization` header when contacting the self-hosted remote cache server configured via `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. | | `NX_SELF_HOSTED_REMOTE_CACHE_SERVER` | string | URL of a self-hosted remote cache server. When set, Nx uses this endpoint for remote cache reads and writes instead of Nx Cloud. | | `NX_SKIP_ATOMIZER_VALIDATION` | boolean | If set to `true`, suppresses the atomizer warning Nx shows when Nx Cloud isn't configured. | | `NX_SKIP_FORMAT` | boolean | If set to `true`, skips code formatting in generators, migrations, `nx init`, `nx import`, and `create-nx-workspace`. Useful for repositories that format with a tool Nx does not drive, such as Biome or dprint, or that have custom formatting requirements. | | `NX_SKIP_LOG_GROUPING` | boolean | If set to `true`, Nx will not group command's logs on CI. | | `NX_SKIP_NATIVE_FILE_CACHE` | boolean | If set to `true`, disables the native `.node` file cache. Nx otherwise copies native bindings to a cache directory to avoid file-locking issues when multiple processes load them. | | `NX_SKIP_PROVENANCE_CHECK` | boolean | If set to `true`, skips `npm` provenance verification when installing packages during `nx migrate`. This is a security-sensitive check. Only disable it if you understand the implications. | | `NX_SKIP_VSCODE_EXTENSION_INSTALL` | boolean | If set to `true`, skips the automatic installation of the Nx Console extension for supported editors. Set this in environments where the temp file that we store this information in otherwise isn't accessible. | | `NX_SOCKET_DIR` | string | Directory for all Nx sockets (daemon, forked process, and plugin). Used as the socket directory itself, replacing the default locations rather than joining them. Mainly a workaround for a socket path that exceeds the OS length limit, or a default location the environment restricts. Takes precedence over `NX_DAEMON_SOCKET_DIR`. Must name a directory only your user can reach. | | `NX_TASKS_RUNNER` | string | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. | | `NX_TASKS_RUNNER_DYNAMIC_OUTPUT` | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version | | `NX_USE_V8_SERIALIZER` | boolean | If set to `true`, Nx will use v8 serialization on its socket channels (the daemon client and server, plugin workers, and pseudo-IPC) instead of JSON. Improves throughput for workspaces with large task payloads. | | `NX_VERBOSE_LOGGING_PATH_MAPPINGS` | boolean | If set to `true`, Nx prints the TypeScript path mappings that it rewrites for buildable library dependencies. | | `NX_WORKSPACE_WALK_WAIT_MS` | number | How long a process waits, in milliseconds, for another process's walk of the workspace before walking it itself. Defaults to `60000`. Values above `3600000` are capped there, `0` never waits, and a value Nx cannot read as a non-negative whole number is ignored in favor of the default. With the daemon running the walk happens in the daemon, which read its environment when it started, so run `nx reset` after changing this. | | `NX_WRAPPER_SKIP_INSTALL` | boolean | If set to `true`, the `.nx/nxw.js` wrapper skips verifying and self-installing the pinned Nx version before each command. | ## Plugin environment variables The following environment variables can be used to configure specific Nx plugins. This is useful in CI environments where the required tooling (e.g., Java) is not available or where plugin behavior needs to be customized. | Property | Type | Description | | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_DOCKER_IMAGE_REF` | string | Full Docker image reference that overrides the configured registry, repository, and generated version during an Nx release. Use the `registry/repository:tag` format. | | `NX_DOTNET_DISABLE` | boolean | If set to `true`, disables the `@nx/dotnet` plugin. Useful in environments where .NET SDK is not available. | | `NX_DOTNET_PROJECT_GRAPH_TIMEOUT` | number | Timeout in seconds for .NET project graph generation. Defaults to `600` in CI and `120` locally. | | `NX_GRADLE_BATCH_DEBUG` | string | JVM options passed to the Java process for the Gradle batch executor. Use this variable to attach a Java debugger to the batch process. | | `NX_GRADLE_DISABLE` | boolean | If set to `true`, disables the `@nx/gradle` plugin. Useful in environments where Java/Gradle is not available. | | `NX_GRADLE_PROJECT_GRAPH_TIMEOUT` | number | Timeout in seconds for Gradle project graph generation. Defaults to `600` in CI and `120` locally. Increase this value for large Gradle workspaces that need more time to resolve. | | `NX_GRADLE_VERBOSE_LOGGING` | boolean | If set to `true`, adds Gradle's `--info` option during project graph generation. | | `NX_MAVEN_DISABLE` | boolean | If set to `true`, disables the `@nx/maven` plugin. Useful in environments where Java/Maven is not available. | | `NX_MAVEN_ANALYSIS_TIMEOUT` | number | Timeout in seconds for Maven analysis. Defaults to `600` in CI and `120` locally. | Nx will set the following environment variables so they can be accessible within the process even outside of executors and generators. | Property | Type | Description | | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_TASK_TARGET_PROJECT` | string | Set to the project name of the task being run. Use this to tell which project is being run. | | `NX_TASK_TARGET_TARGET` | string | Set to the target name of the task being run. Use this to tell which target of the project is being run. | | `NX_TASK_TARGET_CONFIGURATION` | string | Set to the configuration name of the task being run. Use this to tell which configuration of the target is being run. | | `NX_GRAPH_CREATION` | boolean | Set to `true` during the graph creation process. Use this to have inference plugins run different code during graph creation versus during task execution | | `NX_DRY_RUN` | boolean | Set to `true` during dry runs of generators. Use this to avoid side effects during generators. | | `NX_INTERACTIVE` | boolean | Set to `false` when running generators with `--interactive=false`. Use this to prevent prompting during generators | | `NX_RUNNING_NX_IMPORT` | boolean | Set to `true` while the `nx import` command is executing. Use this to have plugin code or scripts behave differently during an import (e.g. adjust telemetry or logging). | | `NX_RUNNING_NX_INIT` | boolean | Set to `true` while the `nx init` command is executing. Use this to have plugin code or scripts behave differently during workspace initialization. | ## Nx Cloud environment variables The following environment variables are specific to Nx Cloud and can be used to configure cloud-specific behavior: {% aside type="tip" title="Verbose Logging" %} Similar to the Nx CLI, Nx Cloud also uses the `NX_VERBOSE_LOGGING` environment variable to output debug information {% /aside %} | Property | Type | Description | | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_BRANCH` | string | The current branch name. For most CI providers, `nx-cloud` determines this automatically. Must be set to the PR number for GitHub, BitBucket and GitLab integrations to work properly. | | `NX_CLOUD_DISABLE_METRICS_COLLECTION` | boolean | Disables collection of CPU and memory metrics during task execution (collected by default on Nx 22.1+). See [Resource Usage](/docs/kb/resource-usage). | | `NX_CLOUD_METRICS_DIRECTORY` | string | Directory where Nx writes resource metrics during task execution. See [Resource Usage](/docs/kb/resource-usage). | | `NX_CI_EXECUTION_ID` | string | A unique identifier for the current CI run or job. For most CI providers, `nx-cloud` determines this automatically. The value on the main job must match the value on all agents. | | `NX_CI_EXECUTION_ENV` | string | Used when you have multiple main jobs (e.g., running CI on both Linux and Windows). The main job with this env variable will connect to agents with the same env name. Also selects the matching [`overrides`](/docs/reference/nx-cloud/ci-config#overrides) entry in `.nx/ci-config.yaml`. | | `NX_AGENT_NAME` | string | Should only be used when you bring your own compute. Names the agent in logs and in the Nx Cloud UI. Falls back to the CircleCI job name, then to a generated name. | | `NX_AGENT_LAUNCH_TEMPLATE` | string | Should only be used when you bring your own compute. Attaches a launch template type to your agents to leverage assignment rules for task distribution. | | `NX_CLOUD_ACCESS_TOKEN` | string | Configure the Nx Cloud access token. Takes precedence over the `accessToken` property in `nx.json`. Common to have a read-only token in `nx.json` and a read-write token set via this environment variable in CI. | | `NX_CLOUD_API` | string | The URL of the Nx Cloud instance to connect to. Overrides `nxCloudUrl` in `nx.json`. | | `NX_CLOUD_CONTINUOUS_ASSIGNMENT` | boolean | Enables continuous assignment for Nx Agents. Required until Nx Cloud enables continuous assignment by default for all workspaces soon. | | `NX_CLOUD_ENCRYPTION_KEY` | string | Enable end-to-end encryption of artifacts. Artifacts will be encrypted/decrypted on your machine. Can also be set via the `nxCloudEncryptionKey` property in `nx.json`. | | `NX_CLOUD_NO_TIMEOUTS` | boolean | Disables the default 10-second timeout for Nx Cloud requests. | | `NX_CLOUD_USE_ULTRACACHE` | boolean | Set to `true` in CI to have Nx hash tasks from Nx Cloud's recordings of the files they read, which is more precise than their declared inputs. Ignored outside CI, and doesn't override a disabled Nx Cloud. | | `NX_NO_OUTPUT_TIMEOUT` | string | Overrides the launch template's [`no-output-timeout`](/docs/kb/launch-templates#launch-templatestemplate-nameno-output-timeout) for an Nx Agent step. Duration string (e.g., `10m`, `1h`); `"0"` disables. | | `NX_NO_CLOUD` | boolean | If set to `true`, prevents Nx Cloud from being used for the current run. No remote cache will be used. Value cannot be set if using [distributed task execution](/docs/features/ci-features/distribute-task-execution) | | `NX_VERBOSE_LOGGING` | boolean | Outputs debug information about agents communicating with the main job. Useful for debugging cache misses and on-premises setup issues. | | `NX_WORKING_DIRECTORY` | string | The subdirectory containing your Nx workspace. Set this in your launch template if your Nx workspace is not at the repository root. Only used by Nx Agents. | | `NX_CLOUD_FORCE_REVALIDATE` | boolean | If set to `true`, forces the Nx Cloud client updater to re-check for a new bundle on every run even when a cached bundle is still valid. Useful when testing new `nx-cloud` client releases. | | `NX_CLOUD_AGENT_TIMEOUT_MS` | number | Timeout in milliseconds an agent waits to hear from Nx Cloud before erroring. Defaults to `3600000` (60 minutes). | | `NX_CLOUD_ORCHESTRATOR_TIMEOUT_MS` | number | Timeout in milliseconds the orchestrator (main job) waits for a completed task response from Nx Cloud. Defaults to `3600000` (60 minutes). | | `NX_CLOUD_NUMBER_OF_RETRIES` | number | How many times Nx Cloud retries HTTP requests that fail with a transient error. Defaults to `10` on CI and `0` locally. | | `NX_CLOUD_DISTRIBUTED_EXECUTION` | boolean | Typically not needed. When set to `false`, disables distributed task execution. Prefer the `--no-dte` or `--no-agents` flags. | ### Deprecated Nx Cloud environment variables | Property | Type | Description | | ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NX_RUN_GROUP` | string | Older versions of `nx-cloud` used this instead of `NX_CI_EXECUTION_ID` and `NX_CI_EXECUTION_ENV`. Served the same purpose. | | `NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE` | boolean | When set to `true`, tells Nx Cloud to stop agents if a command fails. Use [`lifecycle.fail-after`](/docs/reference/nx-cloud/ci-config#lifecyclefail-after) in `.nx/ci-config.yaml` instead, where `1` stops on the first failure and `0` lets the run finish. | | `NX_CLOUD_AUTH_TOKEN` | string | No longer needed. Use `NX_CLOUD_ACCESS_TOKEN` instead. Still read for backwards compatibility. | | `NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT` | number | No longer needed. Nx Cloud now derives the agent count from the launch template and workspace configuration automatically. |