Terraform to OpenTofu Migration: A Practical Guide

Terraform to OpenTofu migration starts with checking compatibility for your configuration. Much Terraform code can be reused, but engine versions, language features, providers, backends, and state consumers need verification. ops0 selects the IaC engine per project, so teams can evaluate a pilot before expanding adoption. OpenTofu describes its compatibility goal and migration process.

This guide covers compatibility checks, a reviewed pilot, recovery planning, and the controls needed while separate projects use different engines.

Why teams move to OpenTofu

OpenTofu exists because Terraform changed its license in 2023 from the open MPL 2.0 to the Business Source License. OpenTofu is the community fork that continues under the original open license, with open governance under the Linux Foundation.

Teams may move for an open-source license, open governance, or particular OpenTofu capabilities. Check the required features as well as the license: the two projects evolve independently. OpenTofu explains its governance and licensing.

OpenTofu vs Terraform: What Differs

The two engines share a starting point. OpenTofu forked from Terraform 1.5, so most configurations, providers, and modules written for Terraform run on OpenTofu with little or no change. Since the fork, each project has shipped features the other does not have yet.

• License: Terraform uses the Business Source License 1.1. OpenTofu uses the Mozilla Public License 2.0 and is governed as a Linux Foundation project.

• OpenTofu-first features: client-side state encryption (1.7), early evaluation of variables in backend and module source blocks (1.8), and for_each on provider configurations (1.9).

• Terraform-first features: HCP Terraform workflows such as Stacks, and language features that ship in Terraform before OpenTofu, such as ephemeral resources in Terraform 1.10.

• Registry: OpenTofu runs its own registry for public providers and modules, so required_providers blocks usually work unchanged.

The practical question is not which engine is better in general. It is whether a given project needs an OpenTofu-first feature, depends on an HCP Terraform workflow, or simply needs an open license. The answer can differ per project, which is why the rest of this guide treats migration as a per-project decision.

Verify compatibility before changing engines

Record the Terraform and proposed OpenTofu versions, provider and module versions, backend settings, and CI commands. Consult the documentation for that combination before changing the project engine. A historical guide for Terraform 1.9 documents differences in functions, S3 settings, removed blocks, and tests; those examples demonstrate why a guide for one version pair is not a universal migration recipe. Read that versioned example.

Language features can also diverge. For example, OpenTofu 1.12 introduced a language block that Terraform does not recognize. Modules intended for both engines need appropriate version constraints and compatible configuration. Review the current language compatibility settings.

Check any hosted runs, policy integrations, private registries, and credentials separately. Changing a CLI command does not move a hosted workspace or reproduce its governance settings.

State dependencies affect migration order

OpenTofu can read Terraform state, but Terraform may not reliably read state written by OpenTofu, especially when OpenTofu-specific features are used. Map terraform_remote_state consumers before a phased migration. The official guide recommends migrating dependent configurations before their dependencies. For example, migrate a subnet project that reads a VPC project's outputs before migrating the VPC project. See the interdependent configuration guide.

A mixed estate means separate projects have a selected engine. Assign one engine to write each project's state during the pilot, and test that its state consumers still work.

How ops0 runs both engines under one model

In ops0, the IaC engine is selected per project. A project can be Terraform, OpenTofu, or Oxid, and the interface stays the same while the engine underneath changes. The command layer routes to the right binary automatically: terraform, tofu, or oxid.

Use the project workflow to review validation, plans, policy results, cost estimates, and approval requirements. Verify these controls against the pilot's engine and providers rather than assuming that accepting HCL proves behavioral parity.

ops0's role is to run and review the selected engine in its project workflow. Selecting OpenTofu does not certify compatibility, migrate a hosted Terraform service, or replace a state recovery plan.

A safe adoption plan

1. 1Choose a low-risk pilot and check its compatibility and state dependencies.
2. 2Back up configuration and state using a protected location and the remote backend's recovery procedure.
3. 3Initialize OpenTofu and compare its plan with the Terraform baseline. Stop if unexpected actions appear.
4. 4Review and approve the first apply. OpenTofu may update state format even without resource changes. Test a small change before expanding.

Follow the current OpenTofu migration guide and verify the pilot's policy, cost, approval, and drift results. Expand only after its dependencies and recovery path have been checked.

Recovery and gradual adoption

If the pilot fails, stop OpenTofu operations. Restore the appropriate backups if state changed, initialize Terraform, and inspect a fresh plan. A state restore is not a rollback of changes already made to cloud resources; reconcile the live environment before approving further actions. OpenTofu provides rollback instructions.

Keep a record of each project's selected engine and versions. Reuse the reviewed process for subsequent projects, while rechecking their providers, backends, and state relationships. The goal is a tested migration with visible decisions and recoverable state.