OpenTofu

The OpenTofu repository is licensed under MPL-2.0, as the GitHub API reports for opentofu/opentofu. Terraform’s own licence is the BSL 1.1, which converts each release to MPL-2.0 on its change date, four years after that version is published (see the introduction page for what the BSL does and does not restrict). In practice the licence matters to three groups: vendors that build competing hosted services, organisations whose policy requires an OSI-approved licence, and anyone who wants a vendor-neutral governance model. For a team that runs the CLI in its own pipelines, the day-to-day effect of the BSL is nil, and the choice is about features and ecosystem rather than law.

The OpenTofu FAQ describes how the project is run: a core team led by a technical lead chooses the most important features and bug fixes, a steering committee decides on big changes, and major changes to OpenTofu core go through a public RFC process guided by community feedback. The project sits under the Linux Foundation, and was accepted by the CNCF as a Sandbox project on 2025-04-23. The FAQ names organisations that back the project, among them Gruntwork, Spacelift, Harness, env0 and Scalr; those are vendors of platforms that run Terraform-compatible workflows, which is one reason the fork has tooling support beyond the CLI.

Each minor series has a bounded security-support window. The changelog of the 1.13 series says it is supported until 2027-08-01, and the unreleased 1.14 series on the main branch says until 2028-02-01. Terraform’s support policy is a HashiCorp matter and is not described on this page.

Source: OpenTofu FAQ, OpenTofu v1.13 CHANGELOG and opentofu/opentofu on GitHub

Terraform downloads providers and modules from registry.terraform.io. OpenTofu’s default is registry.opentofu.org: a provider source address without a hostname, such as hashicorp/aws, means registry.opentofu.org/hashicorp/aws, and if the source argument is omitted entirely OpenTofu implies registry.opentofu.org/hashicorp/<LOCAL NAME>. The OpenTofu documentation recommends explicit source addresses for every provider. Anyone can also host a registry that implements the provider registry protocol under another hostname. The public OpenTofu registry is searchable at search.opentofu.org, which the FAQ describes as separate from the Terraform registry.

Source: OpenTofu Docs — Provider Requirements

The same block resolves to registry.terraform.io/kreuzwerker/docker under Terraform and to registry.opentofu.org/kreuzwerker/docker under OpenTofu. The dependency lock file .terraform.lock.hcl records the provider address, the selected version and the checksums, so the entries made by the two tools name different hostnames. The practical effects are these:

Source: OpenTofu Docs — Migrating from Terraform 1.6, OpenTofu v1.12.0 and OpenTofu v1.12 CHANGELOG

The full treatment of provider requirements, the lock file and mirrors is on Providers.

The standalone installer is one script that serves several install methods. The documentation shows the following flow for Linux, macOS and BSD. It downloads the script, makes it executable, asks you to read it before running it, and removes it afterwards.

Source: OpenTofu Docs — Standalone installation

The standalone method verifies what it downloads. It needs either cosign or GnuPG on the machine, or the option --skip-verify (-skipVerify in PowerShell) to skip the check; in a pipeline, install cosign rather than skipping. The release also publishes a SHA256SUMS file, a signature and a certificate, and the page documents verifying the checksum file with cosign verify-blob against the release workflow identity, as well as comparing the hash of the zip with sha256sum, shasum -a 256 or Get-FileHash. The page itself carries a warning that its sample scripts for macOS and Windows have small mistakes, so read them before you copy them.

Since OpenTofu 1.10 the official images are no longer supported for direct use, and they are not a base image for your own images either: the 1.9 notes already announced this and 1.10 states it. The minimal tags (minimal, 1-minimal, 1.9-minimal and an exact version such as 1.9.1-minimal) hold only the tofu binary at /usr/local/bin/tofu, and the supported use is a multi-stage build that copies it into an image you control.

Source: OpenTofu Docs — Installing OpenTofu with Docker

The Dockerfile follows the documented pattern with the documentation’s example base image; pin the tag and the base image by digest in a real pipeline. The alternative described on the same page is to run the standalone installer in your image with --install-method standalone --install-path /usr/local/bin, which needs bash, curl and gpg in the image.

tenv is a version manager written in Go and described as the successor of tofuenv and tfenv. It manages OpenTofu (tofu), Terraform (terraform and tf), Terragrunt, Terramate and Atmos, installs a proxy binary for each tool, and resolves the version from the environment, from a version file or from a default. That makes it the usual answer to "which binary does this repository use": the proxy chooses.

Source: tenv on GitHub

The version file for OpenTofu is .opentofu-version; Terraform uses .terraform-version (and .tfswitchrc), and tenv also reads .tool-versions and Terragrunt’s constraints. Setting TENV_AUTO_INSTALL to true makes tenv install a missing version on demand, and the tofu and tf commands accept -i for the same purpose. The agnostic tf proxy chooses between OpenTofu and Terraform from the version files alone, so a repository that contains .opentofu-version runs tofu and one that contains .terraform-version runs Terraform. The tenv page does not mention a .tofu-version file. In GitHub Actions the action opentofu/setup-opentofu (current major v2) installs tofu, reads .opentofu-version through its tofu_version_file input and also accepts an asdf-format .tool-versions file.

Source: tenv on GitHub and opentofu/setup-opentofu on GitHub

The current generic guide gives these steps, which this page restates with the Bookshelf commands:

Source: OpenTofu Docs — Migration guide

The state pull backup and the -detailed-exitcode check are additions of this page; the guide asks for a backup and a clean plan but does not prescribe the commands. Do not run tofu apply while Terraform changes are still pending: the version-specific guides say migrating with pending changes is possible but not recommended, and ask for terraform apply to be repeated until terraform plan reports no changes.

For Terraform 1.6 to 1.9 the OpenTofu documentation has one page per Terraform minor version. The pages in the 1.9 documentation set exist for Terraform 1.9, 1.8, 1.7, 1.6 and "1.5 or lower". The current documentation set has only the generic guide above, and I could not find version-specific guides for Terraform 1.10 or later. Each page says the same three things: start from the last patch of that Terraform minor (1.5.7, 1.6.6, 1.7.5, 1.9.8), migrate to a specific OpenTofu release first (1.6.2 for Terraform 1.5 and 1.6, 1.7.1, 1.8.2, 1.9.0), and then upgrade to the latest OpenTofu through the normal upgrade guide.

The incompatibilities these pages list are a snapshot of what differed at that moment, and several have since been closed:

Source: OpenTofu Docs — Migrating from Terraform 1.9, Migrating from Terraform 1.8, Migrating from Terraform 1.7, OpenTofu v1.9 CHANGELOG and OpenTofu v1.10 CHANGELOG

The lesson is to use the guides as a checklist of categories rather than a current list: the backends, the removed block, the built-in terraform provider functions, the test mocks and variable validation are where behaviour has differed, and tofu plan after tofu init is the real test. The upgrade guide for OpenTofu itself adds that new minor series are "typically straightforward" to adopt, asks for a tested recovery plan, a clean tofu plan before the switch and a state backup (tofu state pull for remote state), and describes the rollback.

Source: OpenTofu Docs — Upgrading from earlier release series

If several root modules read each other’s outputs through terraform_remote_state, the order of migration matters. The guide states the rule as "Migrate dependent configurations before their dependencies." The reasoning is that OpenTofu can read Terraform 1.x state, but Terraform may not reliably read state written by OpenTofu, especially when OpenTofu-specific features are in use. A consumer that has been migrated can still read a producer’s Terraform state; a Terraform consumer reading a producer that OpenTofu already wrote may fail. So the order is bottom-up in the dependency graph:

For Bookshelf the shared network and the secrets configuration are read by the application configuration, so the order is application first, then the network and secrets root modules. Track which configurations run on which tool while the migration is in progress; the CI page shows a matrix that runs both.

Source: OpenTofu Docs — Migrating interdependent Terraform configurations

Go through this list before the first tofu plan:

The generic guide’s rollback is short. Stop using OpenTofu, restore state from the backups if any state change was made, run terraform init and terraform plan, and confirm that the plan shows no unexpected changes. That works cleanly only while nothing OpenTofu-specific has entered the configuration or the state. After a successful tofu apply the state has been written by OpenTofu, so a state backup taken before the migration is the safe point, and every change since then is lost unless it is re-applied.

The things that block a return to Terraform are the ones on the other side of the version table:

The OpenTofu pages do not describe a supported way to go back after state has been rewritten beyond the backup-and-restore procedure, so treat the state backup as the only guaranteed path.

OpenTofu code lives in files ending in .tf or .tofu; the JSON variants end in .tf.json or .tofu.json. When a .tf and a .tofu file with the same base name exist in the same directory, OpenTofu loads only the .tofu file and ignores the .tf one: with foo.tf and foo.tofu, foo.tofu wins. The same rule applies to override files (override.tofu and names ending in _override.tofu) and to test files, where .tofutest.hcl and .tofutest.json are read by tofu test and take precedence over .tftest.hcl and .tftest.json of the same base name. The documentation’s use case is exactly this: a module author ships a .tofu file that OpenTofu prefers while the .tf file with the same base name remains for Terraform. Terraform does not load files with the .tofu extension, which is why a file with an OpenTofu-only construct and no .tf twin is simply invisible to Terraform. The .tofu mechanism was added in OpenTofu 1.8.

Source: OpenTofu Docs — Files and directory structure, OpenTofu Docs — Override files and OpenTofu Docs — Settings

The split into versions.tf and versions.tofu is the one the OpenTofu settings page recommends: required_version is kept for Terraform compatibility, and older OpenTofu releases treated it as an OpenTofu constraint, so a versions.tofu file holds either an OpenTofu required_version (when older OpenTofu releases must be supported) or a language block, and the versions.tf file with Terraform’s constraint is ignored by OpenTofu when versions.tofu is present. The language block is accepted only in OpenTofu 1.12 and later and is not recognised by any Terraform version. Its compatible_with block has an opentofu argument, and other tools may define their own arguments. It may also carry edition, whose only valid keyword today is tofu2024 and has no effect, and experiments, a literal list of keywords for experimental features, which a module should omit unless it uses one.

The other technique is not to use the extensions at all and write only constructs that appear in both columns of the version table for the versions you support. A short list of what that rules out in practice: backend or encryption blocks that use variables, provider for_each, enabled, -exclude, oci:// sources, and, in the other direction, action and list blocks, the terraform_data store block and variables in provider requirements. Many teams find that the discipline is cheap because the extensions are used at the edge (the backend, the encryption) rather than in modules.

The third technique tests the configuration with both tools, so that a use of an extension is caught the day it is written. The CI page of this section explains the pipeline in depth; the shape is a matrix over the tool.

Source: opentofu/setup-opentofu and hashicorp/setup-terraform

The action majors are the ones current when this page was written: actions/checkout v7, hashicorp/setup-terraform v4 and opentofu/setup-opentofu v2. Both setup actions install a wrapper script around the binary by default; each has a setting to turn the wrapper off if you depend on exact exit codes or output. See CI/CD and Automation for the full workflow with saved plans and OIDC.

OpenTofu 1.7 introduced optional client-side encryption of state and plan files, for local storage and for every backend. The data is encrypted before it leaves the machine, so the backend only ever stores ciphertext. The state and backend pages of this section show the mechanism in outline (see State and Backends and Remote State); this section is the complete reference.

The encryption block lives inside terraform and has these parts:

Source: OpenTofu Docs — State and plan encryption

Terraform cannot know a state backend before it has initialised, so its backend block accepts only literal values. OpenTofu 1.8 added early evaluation: the backend block, the source and version of module blocks and the encryption block may use input variables and locals, provided they resolve during tofu init, before state is available. References to state data and provider-defined functions are not allowed. Terraform later added the module source and version half of this in 1.15 (see the version table), but still not the backend.

Source: OpenTofu Docs — Backend configuration

The documentation’s own example is a single local used for region; the bucket name above is a Bookshelf adaptation of the same rule. The practical points: the value must be known at init time (a variable that is not supplied is prompted for or fails), the values are written to .terraform/ just like -backend-config values, and the documentation advises against carrying secrets this way and recommends environment variables for credentials. -backend-config files and .tfbackend files remain supported, and a repository that must also run under Terraform keeps using them.

Variables can also drive module sources. The const argument of a variable states explicitly that its value may be used as a constant, that is, without access to state, in module sources and backends. const = true allows it, const = false forbids it even if the value would qualify, and when const is left out OpenTofu inspects the configuration to decide. The argument arrived in OpenTofu 1.12.

Source: OpenTofu Docs — Input variables and OpenTofu Docs — Module sources

The module address above is a placeholder. The pattern with a local also works for a Git source such as ${local.modules_repo}/storage${local.modules_version}, which is the documentation’s own example. Mind the limit stated there: the source and version fields cannot reference state data or provider-defined functions. The modules page of this section covers sources in general (see Modules).

OpenTofu 1.9 added for_each to aliased provider blocks, so one block produces an instance per element of a map, object or set of strings. The instance is selected with a bracketed key, aws.by_region[each.key]. This is useful for Bookshelf’s covers bucket when covers must be replicated to several regions, since it removes one hand-written alias per region.

Source: OpenTofu Docs — Provider configuration

The documented rules: the for_each argument can be used only together with alias; the collection is a map, an object or a set of strings, and the keys become the instance keys; the provider reference (aws.by_region) must stay static and only the bracketed key is dynamic; provider arguments must be known before apply, so variables are safe and resource attributes are not; and a child module can receive a provider instance through providers while declaring the aliases it expects with configuration_aliases. Removing an element is the usual trap: a provider instance has to remain in the configuration until the resources that use it are destroyed, so removal takes extra rounds (see Providers for the workaround).

-exclude=ADDRESS is the complement of -target. It focuses planning on resource instances that do not match the address and that do not depend on it. The two options are mutually exclusive, and the documentation says to use -exclude only in exceptional circumstances, as it does for -target. Since OpenTofu 1.10 the errors about unknown count and for_each values recommend -exclude over -target, and 1.10 added the file forms -exclude-file=FILENAME and -target-file=FILENAME.

Source: OpenTofu Docs — tofu plan

The Terraform 1.17 plan reference does not list -exclude, -concise, -json-into or -show-sensitive. OpenTofu has the first and several more: -concise (1.10) suppresses progress messages, -json-into=FILE (1.12) writes the machine-readable output to a file while the human-readable output stays on the terminal, -show-sensitive (1.9) stops redacting sensitive values, -consolidate-warnings=false turns off warning consolidation, and -deprecation takes module:all (the default), module:local or module:none to control deprecation warnings.

OpenTofu 1.10 added support for registries that implement the OCI Distribution specification (version 1.1.0) as a source of module packages and as a provider mirror. The term here is the Open Container Initiative, the same registries that hold container images; it is unrelated to Terraform’s oci state backend for Oracle Cloud Infrastructure, which has the same three letters.

A module source uses the oci:// prefix, the registry domain and a repository. The default tag is latest, and the tag or digest query argument selects another one, only one of the two at a time.

Source: OpenTofu Docs — Module sources

OpenTofu looks for credentials in the places where the Docker CLI, Podman, Buildah and ORAS store them, so an existing docker login is usually enough. As a provider mirror an OCI registry is a secondary installation source only: it cannot yet be the primary source for a provider. The mirror is configured in the CLI configuration file, with a repository template and include patterns that select which providers come from it.

Source: OpenTofu Docs — Provider mirrors in OCI registries

The template must interpolate every part of the source address that include does not fix exactly (hostname, namespace and type are available). Pushing a mirror has strict requirements: tags are version numbers with an underscore in place of the plus sign in build metadata, the index manifest has the artifactType application/vnd.opentofu.provider, each platform manifest has application/vnd.opentofu.provider-target, and each image manifest has one archive/zip layer with the provider package. The documentation recommends ORAS 1.3.0 or later and pushing to a local directory first. In 1.13 the command tofu providers lock gained the -oci-mirror option, and OCI installs track separate transient credentials per repository.

OpenTofu 1.11 added enabled, written inside a lifecycle block, as an alternative to count = var.flag ? 1 : 0 for a resource or module that exists zero or one times. Unlike count, a single instance keeps its plain address, so there is no [0] to write, and migrating from count needs no moved block: OpenTofu moves the state from the indexed instance to the plain one.

Source: OpenTofu Docs — The enabled meta-argument

When enabled is false the resource evaluates to null, and referencing it directly is an error at plan or apply, so access it with try() or a null check, as the output does. The rules: a resource or module cannot combine enabled with count or for_each; the value must be a known, non-null, non-sensitive, non-ephemeral boolean; and it works on module blocks as well. The lifecycle page of this section compares it with count (see Lifecycle, Validation and Checks).

Terraform processes lifecycle arguments before it evaluates arbitrary expressions, and its reference says that only literal values can be used in the block. OpenTofu 1.12 allows prevent_destroy to refer to other symbols of the same module, such as input variables, so a shared module can protect a production database by default while a development caller turns the protection off. OpenTofu 1.12 also added the destroy lifecycle argument: destroy = false makes OpenTofu forget the instance, removing it from state without destroying the real object. It accepts only constant booleans and is persisted in state.

Source: OpenTofu Docs — Resource behavior and OpenTofu Docs — Resource syntax

The removed block is the documented example; its from address cannot include an instance key. Terraform 1.16 also lists destroy = false in its changelog, although the Terraform 1.17 resource reference page checked for this page does not document it. A tofu destroy that forgets resources exits with a non-zero status unless -suppress-forget-errors is given (1.12).

These are the other additions that matter in practice, grouped by release. Each is taken from the changelog of that version.

Source: OpenTofu v1.9 CHANGELOG, OpenTofu v1.10 CHANGELOG, OpenTofu v1.11 CHANGELOG, OpenTofu v1.12 CHANGELOG, OpenTofu v1.13 CHANGELOG, OpenTofu v1.12.0 and OpenTofu v1.13.0