opentf/website/docs/cli/config/environment-variables.mdx

---
description: >-
  Learn to use environment variables to change OpenTofu's default behavior.
  Configure log content and output, set variables, and more.
---

# Environment Variables

OpenTofu refers to a number of environment variables to customize various
aspects of its behavior. None of these environment variables are required
when using OpenTofu, but they can be used to change some of OpenTofu's
default behaviors in unusual situations, or to increase output verbosity
for debugging.

## TF_LOG

Enables detailed logs to appear on stderr which is useful for debugging. For example:

```shell
export TF_LOG=trace
```

To disable, either unset it, or set it to `off`. For example:

```shell
export TF_LOG=off
```

For more on debugging OpenTofu, check out the section on [Debugging](../../internals/debugging.mdx).

## TF_LOG_PATH

This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running tofu from:

```shell
export TF_LOG_PATH=./terraform.log
```

For more on debugging OpenTofu, check out the section on [Debugging](../../internals/debugging.mdx).

## TF_INPUT

If set to "false" or "0", causes tofu commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example:

```shell
export TF_INPUT=0
```

## TF_VAR_name

Environment variables can be used to set variables. The environment variables must be in the format `TF_VAR_name` and this will be checked last for a value. For example:

```shell
export TF_VAR_region=us-west-1
export TF_VAR_ami=ami-049d8641
export TF_VAR_alist='[1,2,3]'
export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
```

For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](../../language/values/variables.mdx).

## TF_CLI_ARGS and TF_CLI_ARGS_name

<a id="tf-cli-args"></a>

The value of `TF_CLI_ARGS` will specify additional arguments to the
command-line. This allows easier automation in CI environments as well as
modifying default behavior of OpenTofu on your own system.

These arguments are inserted directly _after_ the subcommand
(such as `plan`) and _before_ any flags specified directly on the command-line.
This behavior ensures that flags on the command-line take precedence over
environment variables.

For example, the following command: `TF_CLI_ARGS="-input=false" tofu apply -force`
is the equivalent to manually typing: `tofu apply -input=false -force`.

The flag `TF_CLI_ARGS` affects all OpenTofu commands. If you specify a
named command in the form of `TF_CLI_ARGS_name` then it will only affect
that command. As an example, to specify that only plans never refresh,
you can set `TF_CLI_ARGS_plan="-refresh=false"`.

The value of the flag is parsed as if you typed it directly to the shell.
Double and single quotes are allowed to capture strings and arguments will
be separated by spaces otherwise.

## TF_DATA_DIR

`TF_DATA_DIR` changes the location where OpenTofu keeps its
per-working-directory data, such as the current backend configuration.

By default this data is written into a `.terraform` subdirectory of the
current directory, but the path given in `TF_DATA_DIR` will be used instead
if non-empty.

In most cases it should not be necessary to set this variable, but it may
be useful to do so if e.g. the working directory is not writable.

The data directory is used to retain data that must persist from one command
to the next, so it's important to have this variable set consistently throughout
all of the OpenTofu workflow commands (starting with `tofu init`) or else
OpenTofu may be unable to find providers, modules, and other artifacts.

## TF_WORKSPACE

For multi-environment deployment, in order to select a workspace, instead of doing `tofu workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection.

For example:

```shell
export TF_WORKSPACE=your_workspace
```

Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state.

For more information regarding workspaces, check out the section on [Using Workspaces](../../language/state/workspaces.mdx).

## TF_IN_AUTOMATION

If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTofu adjusts its
output to avoid suggesting specific commands to run next. This can make the
output more consistent and less confusing in workflows where users don't
directly execute OpenTofu commands, like in CI systems or other wrapping
applications.

This is a purely cosmetic change to OpenTofu's human-readable output, and the
exact output differences can change between minor OpenTofu versions.

## TF_REGISTRY_DISCOVERY_RETRY

Equivalent to the `retry_count` setting in the
[Registry Protocol Settings](../../cli/config/config-file.mdx#registry-protocol-settings).

## TF_REGISTRY_CLIENT_TIMEOUT

Equivalent to the `request_timeout_seconds` setting in the
[Registry Protocol Settings](../../cli/config/config-file.mdx#registry-protocol-settings).

## TF_CLI_CONFIG_FILE

The location of the [OpenTofu CLI configuration file](../../cli/config/config-file.mdx).

```shell
export TF_CLI_CONFIG_FILE="$HOME/.tofurc-custom"
```

## TF_PLUGIN_CACHE_DIR

The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](../../cli/config/config-file.mdx#provider-plugin-cache).

You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](../../cli/config/config-file.mdx#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file).

## TF_IGNORE

If `TF_IGNORE` is set to "trace", OpenTofu will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files.

```shell
export TF_IGNORE=trace
```

For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](../../language/settings/backends/remote.mdx#excluding-files-from-upload-with-terraformignore).

## TF_PROVIDER_DOWNLOAD_RETRY

Set `TF_PROVIDER_DOWNLOAD_RETRY` to configure the max number of request retries
the remote provider client will attempt for client connection errors or
500-range responses that are safe to retry.
:::info
This will be used only for the methods without the argument `download_retry_count` specified in [OpenTofu CLI configuration file](./config-file.mdx#explicit-installation-method-configuration).
:::
```shell
export TF_PROVIDER_DOWNLOAD_RETRY=3
```

## TF_STATE_PERSIST_INTERVAL

Set `TF_STATE_PERSIST_INTERVAL` to configure the interval (in seconds) between state persistence.  Increased interval could be useful when working with huge states (> 100k resources) where upload to a cloud service could take a significant amount of time.  Default persistence interval is 20 seconds (it also the lowest possible value for this parameter).  The following command sets persistence interval to 5 minutes (300 seconds):

```shell
export TF_STATE_PERSIST_INTERVAL=300
```

## Cloud Backend CLI Integration

The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTofu configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).

Refer to [Cloud Backend Settings](../../cli/cloud/settings.mdx#environment-variables) for a full list of `cloud` block environment variables.

## TF_ENCRYPTION

The `TF_ENCRYPTION` environment variable is an alternate method of specifying the contents of the `terraform { encryption {} }` block.  If provided, it will be parsed as either HCL or JSON and override configuration present in the .tf config files.

```shell
# Add/Override encryption key_provider.static.mykp
export TF_ENCRYPTION='key_provider "static" "mykp" { key = "6f6f706830656f67686f6834616872756f3751756165686565796f6f72653169" }'
```

:::warning
If the key (or similar) has non-alphanumeric characters in it, beware that your shell may not interpret them literally. Special characters are shell dependent, but some common examples are dollar signs for variable interpolation or backslashes for character escaping.

Make sure your secret doesn't get changed by your shell without you realizing. This is also shell dependent, but common ways of avoiding this are using single quotes or escaping special characters with a backslash.
:::

## TOFU_CPU_PROFILE

Set `TOFU_CPU_PROFILE` to instruct OpenTofu to write a [Go pprof file](https://pkg.go.dev/runtime/pprof). These profiles can be used to help developers identify hot-spots in OpenTofu's codebase that slow down execution.  It pairs well with the more granular and well structured OpenTelemetry tracing (available in OpenTofu 1.10.0). For more information on profiling in Go, see https://go.dev/blog/pprof.  As this uses the go runtime's pprof tooling directly, is not covered under the compatibility promise and is subject to change / removal at any time.

```shell
TOFU_CPU_PROFILE=./tofu.pprof tofu plan
go tool pprof -http ./tofu.pprof
```