OpenTofu Migration from Terraform: Production Guide 2026

OpenTofu: Terraform Migration Guide for Production

When HashiCorp changed Terraform’s license from MPL-2.0 to the Business Source License (BSL) in 2023, the community forked the last open version as OpenTofu — now a Linux Foundation project under open governance. The change rattled many teams because the BSL restricts using Terraform to build a competing commercial product, and that ambiguity matters to anyone embedding infrastructure-as-code in their own platform. Therefore, for organizations evaluating the switch, this guide provides a practical comparison and a step-by-step migration playbook for production environments.

OpenTofu vs Terraform: What Actually Changed

OpenTofu 1.6+ is functionally equivalent to Terraform 1.6 with additions. The core HCL language, provider plugin protocol, state file format, and module system are identical, which is precisely why migration is feasible at all. The key differences are governance and a handful of features: OpenTofu remains MPL-2.0, is steered by a community technical steering committee rather than a single vendor, and adds capabilities such as client-side state encryption and an independent provider registry. Importantly, OpenTofu has continued diverging upward — adding things like provider-defined functions and the -exclude flag — so it is no longer a frozen snapshot of old Terraform.

One of the most compelling additions is native, client-side state encryption. Terraform stores state in plaintext (relying on the backend for at-rest encryption), whereas OpenTofu can encrypt the state before it ever leaves the machine. As a result, even an attacker with read access to your S3 bucket sees only ciphertext. This matters more than it first appears, because state files routinely contain sensitive values — database passwords, generated keys, and resource attributes that providers mark as sensitive in plan output but still persist in state. With encryption enforced, those secrets never sit in plaintext at rest, which simplifies compliance conversations and reduces the blast radius of a misconfigured bucket policy.

# OpenTofu-specific: client-side state encryption
terraform {
  encryption {
    key_provider "aws_kms" "main" {
      kms_key_id = "arn:aws:kms:us-east-1:123456789:key/xxx"
      region     = "us-east-1"
    }
    method "aes_gcm" "main" {
      keys = key_provider.aws_kms.main
    }
    state {
      method   = method.aes_gcm.main
      enforced = true   # refuse to write unencrypted state
    }
  }
}

OpenTofu Migration: Production Checklist

The safest migration is methodical and reversible. Because OpenTofu reads the same state, you can verify each step produces zero drift before committing. The principle is simple: a clean migration shows an empty plan. If tofu plan proposes changes that terraform plan did not, stop and investigate rather than applying.

# Step 1: Install OpenTofu
curl -sLO https://github.com/opentofu/opentofu/releases/download/v1.8.0/tofu_1.8.0_linux_amd64.zip
unzip tofu_1.8.0_linux_amd64.zip -d /usr/local/bin/

# Step 2: Verify compatibility (work on a branch, never main)
cd your-infrastructure/
tofu init            # Downloads providers from the OpenTofu registry
tofu plan            # MUST show "No changes" — anything else is a red flag

# Step 3: State file compatibility check
tofu state list      # Should exactly match `terraform state list`
tofu state show aws_instance.web

# Step 4: Full plan diff between the two binaries
terraform plan -no-color > tf-output.txt   2>&1
tofu      plan -no-color > tofu-output.txt 2>&1
diff tf-output.txt tofu-output.txt         # Expect an empty diff

# Step 5: Commit the new lock file with OpenTofu provider hashes
tofu init -upgrade
git add .terraform.lock.hcl

One subtlety worth flagging: the dependency lock file (.terraform.lock.hcl) records provider checksums. Because OpenTofu pulls providers from its own registry, the recorded hashes may differ even for identical provider versions. Consequently, run tofu init -upgrade and commit the regenerated lock file so your CI runners and teammates download the same artifacts. If you skip this, CI may fail with a checksum mismatch even though nothing about your infrastructure changed, which can be a confusing first impression of the migration.

A second guardrail is worth adopting: never run the migration directly against production state without a backup. Before you point OpenTofu at a live backend, copy the current state somewhere safe — terraform state pull > backup.tfstate — so you can restore it instantly if anything looks wrong. Because the state format is identical, that backup remains valid for either tool, giving you a clean rollback path that takes seconds rather than a rebuild.

CI/CD Pipeline Migration

Your pipelines reference the terraform binary explicitly, so they need updating in lockstep with the local tooling. The change is mostly mechanical — swap the setup action and the command name — but do it on a feature branch so a broken pipeline never blocks production deploys.

# GitHub Actions: Before (Terraform)
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: 1.7.0
- run: terraform init && terraform plan

# GitHub Actions: After (OpenTofu)
- uses: opentofu/setup-opentofu@v1
  with:
    tofu_version: 1.8.0
- run: tofu init && tofu plan

# Atlantis migration — point the runner at the tofu binary
workflows:
  opentofu:
    plan:
      steps:
        - env:
            name: ATLANTIS_TF_BINARY
            value: /usr/local/bin/tofu
        - init
        - plan

Provider Registry and Backend Compatibility

OpenTofu runs its own registry at registry.opentofu.org with most providers mirrored automatically. State backends — S3, GCS, Azure Blob, PostgreSQL, and others — are fully compatible, so you can switch between Terraform and OpenTofu on the same state file without any migration step. This compatibility is the single biggest reason the migration risk is low: there is no irreversible cutover, no state surgery, and no data conversion. In effect, the binary name is the only hard dependency you are changing, and even that can coexist — nothing stops you from keeping both tools installed during a transition period while different teams cut over on their own schedule. For more on managing scale once migrated, see our notes on infrastructure scaling strategies.

Should You Migrate? Honest Trade-offs

Migration is not automatically the right call. Migrate if you are concerned about BSL licensing, you want vendor-neutral community governance, or you specifically want client-side state encryption. By contrast, stay with Terraform if you depend on HCP Terraform (formerly Terraform Cloud) or Terraform Enterprise, have an existing HashiCorp enterprise agreement, or need single-vendor commercial support with an SLA. There are also two practical caveats. First, some HashiCorp-published modules and integrations in the broader ecosystem are validated against Terraform first, so test any third-party tooling. Second, while the registries overlap heavily, occasionally a niche provider version lags behind; verify yours before committing. The migration itself, however, remains genuinely low-risk because both tools read the same state — you can run them side-by-side and roll back instantly.

For further reading, refer to the AWS documentation and the Google Cloud documentation for comprehensive provider reference material.

Key Takeaways

• Start with a solid foundation: migrate on a branch and require an empty plan before merging.
• Test thoroughly in staging — diff the full plan output of both binaries before deploying to production.
• Commit the regenerated .terraform.lock.hcl so every runner uses identical provider artifacts.
• Adopt client-side state encryption to keep secrets out of plaintext state.
• Document the decision and keep a rollback note, since the same state works with either tool.

In conclusion, the OpenTofu Terraform migration is an approachable, low-risk move for teams that value open-source governance. By applying the patterns covered here — install, verify with a zero-change plan, update CI/CD, and adopt encryption — you can switch confidently while retaining the option to roll back. Start with the fundamentals, validate against your real state files, and measure each step so you keep getting the most value from your infrastructure-as-code workflow.