---
description: >-
  The terraform block allows you to configure OpenTofu behavior, including the
  OpenTofu version, backend, integration with TACOS (TF Automation and Collaboration Software),
  and required providers.
---

# OpenTofu Settings

The special `terraform` configuration block type is used to configure some
behaviors of OpenTofu itself, such as requiring a minimum OpenTofu version to
apply your configuration.

:::note
As a part of [OpenTofu v1.x Compatibility Promises](../../language/v1-compatibility-promises.mdx),
the `terraform` block stays as-is. A `tofu` block may be introduced in the future, but it doesn't
exist yet.
:::


## OpenTofu `terraform` Block Syntax

OpenTofu settings are gathered together into `terraform` blocks:

```hcl
terraform {
  # ...
}
```

Each `terraform` block can contain a number of settings related to OpenTofu's
behavior. Within a `terraform` block, only constant values can be used;
arguments may not refer to named objects such as resources, input variables,
etc, and may not use any of the OpenTofu language built-in functions.

The various options supported within a `terraform` block are described in the
following sections.

## Configuring an OpenTofu Backend

The nested `backend` block configures which state backend OpenTofu should use.

The syntax and behavior of the `backend` block is described in
[Backend Configuration](../../language/settings/backends/configuration.mdx).

## Specifying a Required OpenTofu Version

The `required_version` setting accepts a [version constraint string](../../language/expressions/version-constraints.mdx), which specifies which versions of OpenTofu
can be used with your configuration.

If the running version of OpenTofu doesn't match the constraints specified,
OpenTofu will produce an error and exit without taking any further actions.

When you use [child modules](../../language/modules/index.mdx), each module can specify its own
version requirements. The requirements of all modules in the tree must be
satisfied.

Use OpenTofu version constraints in a collaborative environment to
ensure that everyone is using a specific OpenTofu version, or using at least
a minimum OpenTofu version that has behavior expected by the configuration.

The `required_version` setting applies only to the version of OpenTofu CLI.
OpenTofu's resource types are implemented by provider plugins,
whose release cycles are independent of OpenTofu CLI and of each other.
Use [the `required_providers` block](../../language/providers/requirements.mdx) to manage
the expected versions for each provider you use.

## Specifying Provider Requirements

The `required_providers` block specifies all of the providers required by the
current module, mapping each local provider name to a source address and a
version constraint.

```hcl
terraform {
  required_providers {
    aws = {
      version = ">= 2.7.0"
      source = "hashicorp/aws"
    }
  }
}
```

For more information, see [Provider Requirements](../../language/providers/requirements.mdx).

## Experimental Language Features

The OpenTofu team will sometimes introduce new language features initially via
an opt-in experiment, so that the community can try the new feature and give
feedback on it prior to it becoming a backward-compatibility constraint.

In releases where experimental features are available, you can enable them on
a per-module basis by setting the `experiments` argument inside a `tofu`
block:

```hcl
terraform {
  experiments = [example]
}
```

The above would opt in to an experiment named `example`, assuming such an
experiment were available in the current OpenTofu version.

Experiments are subject to arbitrary changes in later releases and, depending on
the outcome of the experiment, may change drastically before final release or
may not be released in stable form at all. Such breaking changes may appear
even in minor and patch releases. We do not recommend using experimental
features in OpenTofu modules intended for production use.

In order to make that explicit and to avoid module callers inadvertently
depending on an experimental feature, any module with experiments enabled will
generate a warning on every `tofu plan` or `tofu apply`. If you
want to try experimental features in a shared module, we recommend enabling the
experiment only in alpha or beta releases of the module.

The introduction and completion of experiments is reported in
[OpenTofu's changelog](https://github.com/opentofu/opentofu/blob/main/CHANGELOG.md),
so you can watch the release notes there to discover which experiment keywords,
if any, are available in a particular OpenTofu release.

## Passing Metadata to Providers

The `terraform` block can have a nested `provider_meta` block for each
provider a module is using, if the provider defines a schema for it. This
allows the provider to receive module-specific information, and is primarily
intended for modules distributed by the same vendor as the associated provider.

For more information, see [Provider Metadata](../../internals/provider-meta.mdx).
