CLI Configuration File (.tofurc or tofu.rc)

The CLI configuration file configures per-user settings for CLI behaviors, which apply across all OpenTofu working directories. This is separate from your infrastructure configuration.

Locations​

The configuration can be placed in a single file whose location depends on the host operating system:

• On Windows, the file must be named tofu.rc and placed in the relevant user's %APPDATA% directory. The physical location of this directory depends on your Windows version and system configuration; use $env:APPDATA in PowerShell to find its location on your system. The terraform.rc is supported for backward-compatability purposes. If both terraform.rc and tofu.rc files exists, the later would take precedence.
• On all other systems, the file must be named .tofurc (note the leading period) and placed directly in the home directory of the relevant user or be named tofurc and placed in a valid XDG Base Directory config directory such as $XDG_CONFIG_HOME/opentofu. The .terraformrc is supported for backward-compatability purposes. If both .terraformrc and .tofurc files exists, the latter would take precedence. When using an XDG config directory .terraformrc and terraformrc are ignored.

On Windows, beware of Windows Explorer's default behavior of hiding filename extensions. OpenTofu will not recognize a file named tofuc.rc.txt as a CLI configuration file, even though Windows Explorer may display its name as just tofu.rc. Use dir from PowerShell or Command Prompt to confirm the filename.

The location of the OpenTofu CLI configuration file can also be specified using the TF_CLI_CONFIG_FILE environment variable. Any such file should follow the naming pattern *.tfrc.

Configuration File Syntax​

The configuration file uses the same HCL syntax as .tf files, but with different attributes and blocks. The following example illustrates the general syntax; see the following section for information on the meaning of each of these settings:

plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"

Available Settings​

The following settings can be set in the CLI configuration file:

• credentials - configures credentials for use with a cloud backend. See Credentials below for more information.

• credentials_helper - configures an external helper program for the storage and retrieval of credentials for cloud backends. See Credentials Helpers below for more information.

• plugin_cache_dir — enables plugin caching and specifies, as a string, the location of the plugin cache directory.

• provider_installation - customizes the installation methods used by tofu init when installing provider plugins. See Provider Installation below for more information.

Credentials​

When interacting with OpenTofu-specific network services, OpenTofu expects to find API tokens in CLI configuration files in credentials blocks:

credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

If you are running the OpenTofu CLI interactively on a computer with a web browser, you can use the tofu login command to get credentials and automatically save them in the CLI configuration. If not, you can manually write credentials blocks.

You can have multiple credentials blocks if you regularly use services from multiple hosts. Each credentials block contains a token argument giving the API token to use for that host.

Environment Variable Credentials​

If you would prefer not to store your API tokens directly in the CLI configuration, you may use a host-specific environment variable. Environment variable names should have the prefix TF_TOKEN_ added to the domain name, with periods encoded as underscores. For example, the value of a variable named TF_TOKEN_app_opentofu_org will be used as a bearer authorization token when the CLI makes service requests to the hostname app.opentofu.org.

You must convert domain names containing non-ASCII characters to their punycode equivalent with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable called TF_TOKEN_xn--r8j3dr99h_com.

Hyphens are also valid within host names but usually invalid as variable names and may be encoded as double underscores. For example, you can set a token for the domain name café.fr as TF_TOKEN_xn--caf-dma.fr, TF_TOKEN_xn--caf-dma_fr, or TF_TOKEN_xn____caf__dma_fr. If multiple variables evaluate to the same hostname, OpenTofu will choose the one defined last in the operating system's variable table.

Credentials Helpers​

You can configure a credentials_helper to instruct OpenTofu to use a different credentials storage mechanism.

credentials_helper "example" {
  args = []
}

credentials_helper is a configuration block that can appear at most once in the CLI configuration. Its label ("example" above) is the name of the credentials helper to use. The args argument is optional and allows passing additional arguments to the helper program, for example if it needs to be configured with the address of a remote host to access for credentials.

A configured credentials helper will be consulted only to retrieve credentials for hosts that are not explicitly configured in a credentials block as described in the previous section. Conversely, this means you can override the credentials returned by the helper for a specific hostname by writing a credentials block alongside the credentials_helper block.

OpenTofu does not include any credentials helpers in the main distribution. To learn how to write and install your own credentials helpers to integrate with existing in-house credentials management systems, see the guide to Credentials Helper internals.

Credentials Source Priority Order​

Credentials found in an environment variable for a particular service host as described above will be preferred over those in CLI config as set by tofu login. If neither are set, any configured credentials helper will be consulted.

Provider Installation​

The default way to install provider plugins is from a provider registry. The origin registry for a provider is encoded in the provider's source address, like registry.opentofu.org/hashicorp/aws. For convenience in the common case, OpenTofu allows omitting the hostname portion for providers on registry.opentofu.org, so you can write shorter public provider addresses like hashicorp/aws.

Downloading a plugin directly from its origin registry is not always appropriate, though. For example, the system where you are running OpenTofu may not be able to access an origin registry due to firewall restrictions within your organization or your locality.

To allow using OpenTofu providers in these situations, there are some alternative options for making provider plugins available to OpenTofu which we'll describe in the following sections.

Explicit Installation Method Configuration​

A provider_installation block in the CLI configuration allows overriding OpenTofu's default installation behaviors, so you can force OpenTofu to use a local mirror for some or all of the providers you intend to use.

The general structure of a provider_installation block is as follows:

provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}

Each of the nested blocks inside the provider_installation block specifies one installation method. Each installation method can take both include and exclude patterns that specify which providers a particular installation method can be used for. In the example above, we specify that any provider whose origin registry is at example.com can be installed only from the filesystem mirror at /usr/share/terraform/providers, while all other providers can be installed only directly from their origin registries.

If you set both include and exclude for a particular installation method, the exclusion patterns take priority. For example, including registry.opentofu.org/hashicorp/* but also excluding registry.opentofu.org/hashicorp/dns will make that installation method apply to everything in the hashicorp namespace with the exception of hashicorp/dns.

As with provider source addresses in the main configuration, you can omit the registry.opentofu.org/ prefix for providers distributed through the public OpenTofu Registry, even when using wildcards. For example, registry.opentofu.org/hashicorp/* and hashicorp/* are equivalent. */* is a shorthand for registry.opentofu.org/*/*, not for */*/*.

The following are the supported installation method types:

• direct: request information about the provider directly from its origin registry and download over the network from the location that registry indicates. This method expects no additional arguments.

• filesystem_mirror: consult a directory on the local disk for copies of providers. This method requires the additional argument path to indicate which directory to look in.

  OpenTofu expects the given directory to contain a nested directory structure where the path segments together provide metadata about the available providers. The following two directory structures are supported:

  • Packed layout: HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip is the distribution zip file obtained from the provider's origin registry.
  • Unpacked layout: HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET is a directory containing the result of extracting the provider's distribution zip file.

  In both layouts, the VERSION is a string like 2.0.0 and the TARGET specifies a particular target platform using a format like darwin_amd64, linux_arm, windows_amd64, etc.

  If you use the unpacked layout, OpenTofu will attempt to create a symbolic link to the mirror directory when installing the provider, rather than creating a deep copy of the directory. The packed layout prevents this because OpenTofu must extract the zip file during installation.

  You can include multiple filesystem_mirror blocks in order to specify several different directories to search.

• network_mirror: consult a particular HTTPS server for copies of providers, regardless of which registry host they belong to. This method requires the additional argument url to indicate the mirror base URL, which should use the https: scheme and end with a trailing slash.

  OpenTofu expects the given URL to be a base URL for an implementation of the provider network mirror protocol, which is designed to be relatively easy to implement using typical static website hosting mechanisms.

OpenTofu will try all of the specified methods whose include and exclude patterns match a given provider, and select the newest version available across all of those methods that matches the version constraint given in each OpenTofu configuration. If you have a local mirror of a particular provider and intend OpenTofu to use that local mirror exclusively, you must either remove the direct installation method altogether or use its exclude argument to disable its use for specific providers.

Implied Local Mirror Directories​

If your CLI configuration does not include a provider_installation block at all, OpenTofu produces an implied configuration. The implied configuration includes a selection of filesystem_mirror methods and then the direct method.

The set of directories OpenTofu can select as filesystem mirrors depends on the operating system where you are running OpenTofu:

• Windows: %APPDATA%/terraform.d/plugins and %APPDATA%/HashiCorp/Terraform/plugins
• Mac OS X: $HOME/.terraform.d/plugins, ~/Library/Application Support/io.terraform/plugins, and /Library/Application Support/io.terraform/plugins
• Linux and other Unix-like systems:$HOME/.terraform.d/plugins and opentofu/plugins located within a valid XDG Base Directory data directory such as $XDG_DATA_HOME/opentofu/plugins.

If a terraform.d/plugins directory exists in the current working directory then OpenTofu will also include that directory, regardless of your operating system. This behavior changes when you use the -chdir option with the init command. In that case, OpenTofu checks for the terraform.d/plugins directory in the launch directory and not in the directory you specified with -chdir.

OpenTofu will check each of the paths above to see if it exists, and if so treat it as a filesystem mirror. The directory structure inside each one must therefore match one of the two structures described for filesystem_mirror blocks in Explicit Installation Method Configuration.

In addition to the zero or more implied filesystem_mirror blocks, OpenTofu also creates an implied direct block. OpenTofu will scan all of the filesystem mirror directories to see which providers are placed there and automatically exclude all of those providers from the implied direct block. (This automatic exclude behavior applies only to implicit direct blocks; if you use explicit provider_installation you will need to write the intended exclusions out yourself.)

Provider Plugin Cache​

By default, tofu init downloads plugins into a subdirectory of the working directory so that each working directory is self-contained. As a consequence, if you have multiple configurations that use the same provider then a separate copy of its plugin will be downloaded for each configuration.

Given that provider plugins can be quite large (on the order of hundreds of megabytes), this default behavior can be inconvenient for those with slow or metered Internet connections. Therefore OpenTofu optionally allows the use of a local directory as a shared plugin cache, which then allows each distinct plugin binary to be downloaded only once.

To enable the plugin cache, use the plugin_cache_dir setting in the CLI configuration file. For example:

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

This directory must already exist before OpenTofu will cache plugins; OpenTofu will not create the directory itself.

Please note that on Windows it is necessary to use forward slash separators (/) rather than the conventional backslash (\) since the configuration file parser considers a backslash to begin an escape sequence.

Setting this in the configuration file is the recommended approach for a persistent setting. Alternatively, the TF_PLUGIN_CACHE_DIR environment variable can be used to enable caching or to override an existing cache directory within a particular shell session:

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"

When a plugin cache directory is enabled, the tofu init command will still use the configured or implied installation methods to obtain metadata about which plugins are available, but once a suitable version has been selected it will first check to see if the chosen plugin is already available in the cache directory. If so, OpenTofu will use the previously-downloaded copy.

If the selected plugin is not already in the cache, OpenTofu will download it into the cache first and then copy it from there into the correct location under your current working directory. When possible OpenTofu will use symbolic links to avoid storing a separate copy of a cached plugin in multiple directories.

The plugin cache directory must not also be one of the configured or implied filesystem mirror directories, since the cache management logic conflicts with the filesystem mirror logic when operating on the same directory.

OpenTofu will never itself delete a plugin from the plugin cache once it has been placed there. Over time, as plugins are upgraded, the cache directory may grow to contain several unused versions which you must delete manually.

Allowing the Provider Plugin Cache to break the dependency lock file​

By default OpenTofu will use packages from the global cache directory only if they match at least one of the checksums recorded in the dependency lock file for that provider. This ensures that OpenTofu can always generate a complete and correct dependency lock file entry the first time you use a new provider in a particular configuration.

However, we know that in some special situations teams have been unable to use the dependency lock file as intended, and so they don't include it in their version control as recommended and instead let OpenTofu re-generate it each time it installs providers.

For those teams that don't preserve the dependency lock file in their version control systems between runs, OpenTofu allows an additional CLI Configuration setting which tells OpenTofu to always treat a package in the cache directory as valid even if there isn't already an entry in the dependency lock file to confirm it:

plugin_cache_may_break_dependency_lock_file = true

Alternatively, you can set the environment variable TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE to any value other than the empty string or 0, which is equivalent to the above setting.

Setting this option gives OpenTofu CLI permission to create an incomplete dependency lock file entry for a provider if that would allow OpenTofu to use the cache to install that provider. In that situation the dependency lock file will be valid for use on the current system but may not be valid for use on another computer with a different operating system or CPU architecture, because it will include only a checksum of the package in the global cache.

We recommend that most users leave this option unset, in which case OpenTofu will always install a provider from upstream the first time you use it with a particular configuration, but can then re-use the cache entry on later runs once the dependency lock file records valid checksums for the provider package.

Development Overrides for Provider Developers​

Normally OpenTofu verifies version selections and checksums for providers in order to help ensure that all operations are made with the intended version of a provider, and that authors can gradually upgrade to newer provider versions in a controlled manner.

These version and checksum rules are inconvenient when developing a provider though, because we often want to try a test configuration against a development build of a provider that doesn't even have an associated version number yet, and doesn't have an official set of checksums listed in a provider registry.

As a convenience for provider development, OpenTofu supports a special additional block dev_overrides in provider_installation blocks. The contents of this block effectively override all of the other configured installation methods, so a block of this type must always appear first in the sequence:

provider_installation {

  # Use /home/developer/tmp/terraform-null as an overridden package directory
  # for the hashicorp/null provider. This disables the version and checksum
  # verifications for this provider and forces OpenTofu to look for the
  # null provider plugin in the given directory.
  dev_overrides {
    "hashicorp/null" = "/home/developer/tmp/terraform-null"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, OpenTofu will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

With development overrides in effect, the tofu init command will still attempt to select a suitable published version of your provider to install and record in the dependency lock file for future use, but other commands like tofu apply will disregard the lock file's entry for hashicorp/null and will use the given directory instead. Once your new changes are included in a published release of the provider, you can use tofu init -upgrade to select the new version in the dependency lock file and remove your development override.

The override path for a particular provider should be a directory similar to what would be included in a .zip file when distributing the provider. At minimum that includes an executable file named with a prefix like terraform-provider-null, where null is the provider type. If your provider makes use of other files in its distribution package then you can copy those files into the override directory too.

You may wish to enable a development override only for shell sessions where you are actively working on provider development. If so, you can write a local CLI configuration file with content like the above in your development directory, perhaps called dev.tfrc for the sake of example, and then use the TF_CLI_CONFIG_FILE environment variable to instruct OpenTofu to use that localized CLI configuration instead of the default one:

export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc

Development overrides are not intended for general use as a way to have OpenTofu look for providers on the local filesystem. If you wish to put copies of released providers in your local filesystem, see Implied Local Mirror Directories or Explicit Installation Method Configuration instead.

This development overrides mechanism is intended as a pragmatic way to enable smoother provider development. The details of how it behaves, how to configure it, and how it interacts with the dependency lock file may all evolve in future OpenTofu releases, including possible breaking changes. We therefore recommend using development overrides only temporarily during provider development work.