🔀 Migrating From Terraform to OpenTofu: A Practical Guide

When HashiCorp relicensed Terraform under the BUSL, OpenTofu emerged as the open-source, MPL-licensed fork. I’ve now evaluated and run the migration on real estates, and the good news is that for most teams it’s far less dramatic than it sounds. The bad news is it’s not zero-effort, and rushing it across a large estate without a plan is how you turn a clean swap into a weekend of state debugging.

Here’s how I approach it.

What OpenTofu actually is

OpenTofu is a community-governed fork of Terraform, maintained under the Linux Foundation, that stays largely compatible with the Terraform CLI and HCL you already write. The tofu binary is close to a drop-in replacement for recent Terraform versions, reads the same .tf files, and uses the same providers from the registry.

The two honest reasons teams migrate: avoiding the BUSL license terms, and wanting features the open-source fork ships independently (like native state encryption). If neither matters to you, there’s no obligation to move.

Decide before you migrate

I make the decision deliberately, not reflexively:

• License posture — does the BUSL genuinely affect how your org uses Terraform? For most internal infra users, it doesn’t restrict day-to-day use. For vendors building products on it, it can.
• Version alignment — OpenTofu forked from Terraform 1.5.x and has since diverged. Newer Terraform language features may land at different times. Check that the features you rely on exist in the OpenTofu version you’d target.
• Tooling ecosystem — CI runners, IDE plugins, and wrappers like Terragrunt all support OpenTofu, but verify your specific stack.

If the answer is “we want open-source guarantees and our features are covered,” proceed.

The migration is mostly a binary swap

For an estate already on Terraform 1.5 or 1.6, the core migration is straightforward:

# install opentofu, then in a workspace:
tofu init
tofu plan

OpenTofu reads your existing state and config. A clean tofu plan showing zero changes is the signal that the swap is behaviorally compatible for that workspace. The state format is compatible, so you’re not converting state — you’re pointing a different binary at it.

Stage it like any risky rollout

Never flip the whole estate at once:

1. Pilot one non-production workspace. Run tofu init && tofu plan and confirm zero unexpected diffs.
2. Update CI for that workspace to call tofu instead of terraform, and verify the pipeline is green end to end.
3. Validate state operations — a plan, a trivial apply, a state list — all behave.
4. Promote tier by tier, dev to staging to prod, watching each plan.

Back up state before each tier. The backend’s versioning is your safety net, but a clean snapshot before the first tofu apply per workspace costs nothing.

Watch the genuine gotchas

A few things that actually trip people:

• Version drift between binaries — if some engineers run terraform and others run tofu against the same state, pin one tool per estate to avoid format surprises.
• .terraform.lock.hcl — re-run init so the lock file resolves providers under the tool you’re standardizing on.
• Wrapper config — Terragrunt and similar need a one-line setting to invoke tofu.

Where AI helps with the migration

AI is useful for the assessment and the diffing. I’ll feed it the OpenTofu and Terraform changelogs and ask: “Which features my estate uses have diverged between these versions?” That turns a tedious changelog crawl into a short, relevant list.

It’s also handy for explaining any unexpected tofu plan diff during the pilot — usually a provider resolving slightly differently. I keep migration-assessment Terraform prompts for this, and I run the CI changes that swap the binary through our Code Review tool so nothing references the old tool by accident.

As always, AI assesses and explains; I run the plans and applies, watching each one.

The takeaway

Migrating to OpenTofu is, for most estates, a staged binary swap rather than a rewrite — the state format and HCL carry over. Make the license-and-features decision deliberately, pilot one workspace, confirm a zero-change plan, then promote tier by tier with backups. Standardize on one tool to avoid drift, and you’ll move without drama.