Tutorial

Terraform vs OpenTofu in 2026: A Safe Migration Walkthrough

Migrate from Terraform to OpenTofu safely: a hands-on walkthrough of state, state encryption, rollback, and the gotchas that trip teams up.

·
13 min read
·
AI-assisted

AI tooling disclosure

Generative AI materially contributed to this article.

Human review confirmed by the author.

Terraform vs OpenTofu in 2026: A Safe Migration Walkthrough

Your Terraform repo has worked fine for years. Then someone on the team asks, "Should we be on OpenTofu?" and nobody has a good answer.

The honest answer is "maybe, and the move is usually easier than people fear." But there are a few places where it can bite you, and several of them involve state.

In this post you'll see how the two tools differ today, how to migrate one project step by step (with a demo that runs on your laptop and needs no cloud account), how to handle state and its encryption, and which gotchas trip people up most often.

TL;DR

  • For most projects, migrating means swapping the terraform binary for tofu and checking that tofu plan shows no changes.

  • OpenTofu can read Terraform state, but Terraform may not reliably read state written by OpenTofu. Treat the switch as a one-way door and back up first.

  • The biggest technical difference today is built-in state encryption, which OpenTofu has and Terraform doesn't.

  • Migrate first, adopt OpenTofu-only features later. Changing two things at once makes failures hard to diagnose.

  • The usual traps are version constraints, the provider registry and lock file, terraform_remote_state ordering, HCP Terraform, and CI tooling that still calls terraform.

How we got here

A short timeline, so the rest makes sense:

  • August 2023: HashiCorp announces that it is moving Terraform to the Business Source License (BUSL 1.1), which is source-available but not open source. A community fork, first called OpenTF, follows. It is later renamed OpenTofu and moved under the Linux Foundation.

  • September 2023: Terraform 1.5.7 is the last release under the open-source MPL 2.0 license. From 1.6.0 onward, Terraform ships under the BUSL.

  • April 2024: OpenTofu 1.7 ships with client-side state encryption.

  • February 2025: IBM completes its acquisition of HashiCorp, so IBM is now the licensor of Terraform.

  • September 2026: OpenTofu 1.13.0 is released. Its security support runs until August 2027.

Does the license matter to you? It depends. The BUSL mainly restricts people who build products that compete with HashiCorp's offerings. If you only use Terraform to manage your own infrastructure, you probably aren't affected today. It matters more if you're a vendor or consultancy embedding the tool, if your company requires open-source licenses, or if you simply don't want to depend on one company's future licensing decisions.

Terraform vs OpenTofu at a glance

The core workflow is the same: write HCL, run init, plan and apply, keep state somewhere. Here's where they differ.

Terraform

OpenTofu

License

BUSL 1.1 (since 1.6.0)

MPL 2.0

Steward

HashiCorp, now part of IBM

Linux Foundation project, community governed

Binary

terraform

tofu

Providers

Terraform Registry

Same providers, separate registry (registry.opentofu.org)

State encryption

Not built in; you rely on backend encryption or external tools

Built in since 1.7, for state and plan files

for_each on provider configs

Not available in regular configurations (only in Stacks)

Since 1.9

Ephemeral values and write-only attributes

Available

Available since 1.11

enabled meta-argument (alternative to count = x ? 1 : 0)

Not available

Since 1.11

HCP Terraform and Stacks

Yes

Not part of OpenTofu

Heads up: The two projects keep diverging. OpenTofu doesn't promise to track every Terraform release, and Terraform doesn't track OpenTofu. A config that works in both tools today can stop doing so once you use a feature that only one of them has.

Should you move?

Staying on Terraform makes sense if:

  • You rely on HCP Terraform features, enterprise agreements or Stacks.

  • Your team's training and documentation are built around Terraform and nothing is pushing you to change.

  • You don't need anything OpenTofu offers and don't mind the BUSL.

Moving to OpenTofu makes sense if:

  • You need an open-source license or vendor-neutral governance.

  • You want state encryption without extra tooling.

  • You want features such as provider for_each or the enabled meta-argument.

Both are reasonable. The rest of this post assumes you've decided to try the move.

Pre-flight checklist

Do this before you touch anything:

  1. Get to a clean Terraform plan. terraform plan should show no changes. Switching tools with pending changes is a bad idea.

  2. Standardize versions. If your configs run different Terraform versions, bring them to the same version first. It narrows down what could go wrong.

  3. Inventory your root modules. List every config, its backend, and which ones read each other's state with terraform_remote_state. (grep -r terraform_remote_state . is a good start.)

  4. Check your providers and modules. Search for each at search.opentofu.org. Most are there, but a missing one will stop tofu init.

  5. Look at your tooling. Note every place that runs terraform: CI pipelines, Makefiles, pre-commit hooks, Docker images, Terragrunt or Atlantis configs and IDE plugins.

  6. Check whether you use HCP Terraform (Terraform Cloud). That is a bigger migration. See the gotchas below.

  7. Back up state. More on this in the walkthrough.

The migration at a glance

flowchart TD
    A["Back up state and code"] --> B["Install OpenTofu"]
    B --> C["tofu init"]
    C --> D["tofu plan"]
    D --> E{"No changes?"}
    E -->|"Yes"| F["tofu apply"]
    E -->|"No"| G["Stop. Do not apply.<br/>Investigate or roll back"]
    F --> H["Make one small change<br/>and plan/apply again"]
    H --> I["Only now: adopt OpenTofu-only features"]

Hands-on: migrate a demo project

You'll create a tiny project with Terraform, then move it to OpenTofu. It uses the random provider and the built-in terraform_data resource, so it needs no cloud account.

Step 0: Create the starting point

Create a folder and a main.tf:

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

resource "random_pet" "app" {
  length = 2
}

resource "terraform_data" "release" {
  input = "release-${random_pet.app.id}"
}

output "app_name" {
  value = random_pet.app.id
}

Apply it with Terraform so you have real state to migrate:

terraform init
terraform apply -auto-approve
terraform plan   # should say there are no changes

Step 1: Back up state and code

For local state, as in this demo:

mkdir -p backup
cp terraform.tfstate* .terraform.lock.hcl backup/
git add -A && git commit -m "Pre-OpenTofu snapshot"

For remote state, use your backend's own backup. For S3 that means turning on bucket versioning. You can also save a copy:

terraform state pull > backup/state-before-tofu.json

Step 2: Install OpenTofu

Follow the install guide for your platform, then check it:

tofu --version

Keep Terraform installed on your own machine for now. You'll want it for rollback.

Step 3: Initialize

tofu init

This downloads providers from the OpenTofu registry, initializes your backend, and prepares the working directory. Check what changed in the lock file:

git diff .terraform.lock.hcl

You should see provider entries for the OpenTofu registry. Commit the updated lock file along with the migration.

Step 4: Plan and look for "no changes"

tofu plan

You should see "No changes." If you see changes, do not apply them. Find out why first. If you can't explain it, roll back (see below).

Step 5: Apply

tofu apply

Even with no infrastructure changes, this step lets OpenTofu write the state in its own format.

This is the point of no easy return. After this, the state has been written by OpenTofu. If you need to go back to Terraform, restore your backup rather than assuming Terraform can read the new state.

Step 6: Make one small change

Edit main.tf and change the terraform_data input:

resource "terraform_data" "release" {
  input = "release-${random_pet.app.id}-v2"
}
tofu plan
tofu apply

An in-place update with no surprises tells you OpenTofu can manage this project from here on.

State handling in depth

Compatibility goes one way

OpenTofu reads Terraform 1.x state files without modification. The reverse isn't guaranteed. Terraform may not reliably read state written by OpenTofu, especially if you've used OpenTofu-only features.

Practical rules:

  • One tool per state file. After you migrate a state, nobody runs terraform apply against it again.

  • Keep backups and versioning on until you've lived with the new setup for a while.

  • Treat saved plan files as tool-specific. Apply a plan with the same tool that created it.

Remote backends

Your backend block stays the same. tofu init reads it as is. Two tips:

  • Don't change the backend and the tool in the same PR. If something breaks, you won't know which change caused it.

  • Change locking separately. OpenTofu 1.10 added native S3 state locking, so you can drop DynamoDB. That's a worthwhile cleanup, but do it as its own change, after the migration:

terraform {
  backend "s3" {
    bucket       = "my-state-bucket"
    key          = "prod/network/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

Multiple configs that read each other's state

If one config reads another's outputs through terraform_remote_state, order matters.

A  (VPC)            producer: others read A's state
       / \
      B   C                 consumers of A
      |
      D                     consumer of B

The rule from the OpenTofu docs is to migrate consumers before the configs they read from. Here that means D first, then B and C, and A last.

Why? If you migrate A first, B and C (still on Terraform) would have to read state that OpenTofu wrote, and that direction isn't guaranteed to work. Migrating consumers first avoids the problem.

After each config, run a plan on the configs that depend on it and confirm there are no unexpected changes. Avoid OpenTofu-only features until the whole chain has moved.

State encryption (do it after the migration)

This is OpenTofu's headline feature. State files often contain secrets, such as passwords and access keys. OpenTofu can encrypt state and plan files at rest, before they reach the backend.

Do this as a separate step from the migration. Once you encrypt, Terraform can't read the state, and your rollback path gets harder.

Create encryption.tf:

variable "state_passphrase" {
  type      = string
  sensitive = true
}

terraform {
  encryption {
    # Lets OpenTofu read your existing unencrypted state during the transition
    method "unencrypted" "migrate" {}

    key_provider "pbkdf2" "main" {
      passphrase = var.state_passphrase
    }

    method "aes_gcm" "main" {
      keys = key_provider.pbkdf2.main
    }

    state {
      method = method.aes_gcm.main

      fallback {
        method = method.unencrypted.migrate
      }
    }

    plan {
      method = method.aes_gcm.main

      fallback {
        method = method.unencrypted.migrate
      }
    }
  }
}

Set the passphrase outside your code, then apply:

export TF_VAR_state_passphrase='use-a-long-random-passphrase-here'
tofu apply

OpenTofu reads the old plain state through the fallback and writes the new state encrypted. With local state you can see the difference: terraform.tfstate no longer contains your resource values in plain text, only encrypted data plus metadata such as the key provider's name. Run tofu plan once to confirm OpenTofu can read it back.

Once that works, remove the fallback and require encryption from now on:

state {
      method   = method.aes_gcm.main
      enforced = true
    }

    plan {
      method   = method.aes_gcm.main
      enforced = true
    }

Remove the method "unencrypted" block too, then run tofu plan to confirm everything still works. Run it with the wrong passphrase and OpenTofu stops with decryption failed: cipher: message authentication failed. That is exactly what you want.

Rules that will save you:

  • Back up your key and your unencrypted state first. Without the key, encrypted state is unrecoverable.

  • Don't rename key providers or methods after encrypting. The encrypted data stores their names. Use a fallback block when you change keys, or set encrypted_metadata_alias on the key provider.

  • Pick the key type on purpose. A static passphrase must be long and complex (at least 16 characters). With a key management service (AWS KMS, GCP KMS, Azure Key Vault or OpenBao), use a separate key per state file and make sure keys rotate automatically. AES-GCM can suffer from key saturation if you reuse a short static key too long.

  • Know what encryption doesn't do. It protects data at rest. It doesn't protect against data loss, replay of an old state or plan file, or the person running tofu.

  • Use enforced = true in code if you pass encryption config through the TF_ENCRYPTION environment variable, so a missing variable can't silently write unencrypted state.

  • Let other configs decrypt it. If a config reads this state with terraform_remote_state, add a remote_state_data_sources block so it can decrypt it.

  • Know the way back. To return to unencrypted state, reverse the process: make the unencrypted method primary and move your old method into fallback. Don't remove the old method until the migration finishes.

Gotchas

1. required_version means different things in the two tools

OpenTofu 1.13 is not "older" or "newer" than a given Terraform release. The version numbers are independent, so a constraint written for one tool says nothing reliable about the other.

Older OpenTofu releases read required_version as an OpenTofu constraint everywhere, which was a headache for modules written for Terraform. Current releases treat it differently: in a plain .tf file it is read as a Terraform constraint, and OpenTofu 1.13.0 doesn't enforce it. This config plans fine on OpenTofu 1.13.0 even though it asks for Terraform 1.14 or newer:

terraform {
  required_version = ">= 1.14.0"
}

That removes an old migration blocker, but it also removes a guardrail: nothing stops a teammate from running an OpenTofu version that is too old for your code.

The OpenTofu docs recommend splitting the constraint into two small files, one per tool:

# versions.tf (read by Terraform)
terraform {
  required_version = ">= 1.14.0"
}

# versions.tofu (read by OpenTofu)
terraform {
  required_version = ">= 1.9.0"
}

When both files exist, OpenTofu ignores versions.tf. According to the OpenTofu docs, Terraform doesn't read .tofu files at all. On OpenTofu 1.13.0, a constraint in versions.tofu that isn't met stops the run with an Incompatible module error. OpenTofu 1.12 and later also offer a language block for this, for example compatible_with { opentofu = ">= 1.12" }.

Check the required_version in your root modules and the modules you consume, and test against the exact OpenTofu version your CI will pin, because older releases behave differently.

2. Registry and lock file changes

tofu init pulls providers from the OpenTofu registry by default, so .terraform.lock.hcl changes. Commit it.

  • If you build the lock file on one machine and run CI on another OS, add hashes for every platform you use:

    tofu providers lock -platform=linux_amd64 -platform=darwin_arm64
  • Source addresses that explicitly point to registry.terraform.io may need updating.

  • If a provider or module isn't in the OpenTofu registry, tofu init fails with a message like Failed to query available provider packages or Module not found. Roll back and ask for it to be added to the registry.

3. Don't mix migration and new features

The docs say to avoid OpenTofu-only features during the migration. If you use enabled, provider for_each or encryption on day one, you lose both an easy rollback and the ability to tell which change caused a problem.

When you're ready, .tofu files give you a way to add OpenTofu-only code to a module that Terraform users also consume. OpenTofu loads a .tofu file instead of the .tf file with the same name, and loads a .tofu file with a different name in addition to your .tf files. Terraform doesn't read .tofu files (see gotcha 1), so it never sees them:

main.tf        # works in both tools
main.tofu      # OpenTofu loads this instead of main.tf
extra.tofu     # OpenTofu loads this as well; Terraform ignores it

4. Version hops

Don't combine the migration with a big version jump. The older OpenTofu migration guides were written per Terraform version (for example 1.7.x) and said to migrate to the matching OpenTofu version first, then upgrade OpenTofu afterwards. The current docs have a single general guide, and a clean tofu plan is what tells you the move worked. Either way, migrate first and upgrade later.

5. Plans can change after an OpenTofu upgrade

Even after a clean migration, a later OpenTofu upgrade can show harmless-looking changes. For example, in 1.13 the base64gzip function produces results that are equivalent but not byte-for-byte identical to earlier versions. If you use it in a resource argument, your plan may show a change. The OpenTofu team's workaround is to add ignore_changes temporarily, until you're ready to accept the new value.

Read the release notes before every upgrade.

6. HCP Terraform is a bigger move

If your state lives in HCP Terraform (Terraform Cloud), this isn't a binary swap. You're also changing where state is stored and where runs happen. Plan for:

  • A new home for state, such as S3, GCS or Azure Blob. A cloud {} block won't simply carry over: OpenTofu has its own cloud backend that requires an explicit hostname and has no default, so it won't point at HCP Terraform on its own.

  • Workspace variables, run triggers and policy checks (for example Sentinel) that don't move with the state.

  • A CI-based or third-party workflow to replace remote runs.

The conservative way to move the state itself is to pull it while you're still on Terraform, point the config at the new backend, then push it:

terraform state pull > backup/state.json    # still on Terraform
# edit your backend config to the new backend, then:
tofu init
tofu state push backup/state.json
tofu plan                                   # expect: No changes

Treat it as its own project with its own rollback plan.

7. Tooling still calls terraform

Search for it everywhere:

  • CI pipelines. Use the opentofu/setup-opentofu action and pin the version.

  • Makefiles, shell scripts and pre-commit hooks.

  • Docker images and dev containers.

  • Terragrunt, Atlantis and similar wrappers. Point them at the tofu binary (check their docs for the current setting).

  • Linters and scanners. Most work on HCL files and don't care, but check.

8. The stray terraform apply

The most realistic way to hurt yourself after a migration is a teammate running terraform apply out of habit. Make the switch loud:

  • Remove Terraform from CI images and shared dev containers.

  • Add a note to the repo's README and PR template.

  • Apply only through CI where you can.

Rolling back

If something goes wrong before your first tofu apply, you've changed nothing. Just go back to Terraform.

If it goes wrong after:

  1. Stop using OpenTofu.

  2. Restore your state backup if OpenTofu changed the state.

  3. Run terraform init and terraform plan.

  4. Confirm there are no unexpected changes.

  5. Carry on with Terraform.

Where you are

Can you roll back?

Before the first tofu apply

Yes, nothing changed

After apply, no OpenTofu-only features

Yes, restore the backed-up state and re-plan with Terraform

After using OpenTofu-only features

Harder. Remove those features first, then restore and re-plan

After enabling state encryption

Roll back encryption first (or restore your unencrypted backup), then go back to Terraform

Migration checklist

Copy this into your ticket:

  • terraform plan is clean on every root module

  • All configs on the same Terraform version

  • Providers and modules checked at search.opentofu.org

  • Version constraints sorted: versions.tf for Terraform, versions.tofu for OpenTofu

  • Dependency graph mapped, terraform_remote_state order decided (consumers first)

  • State backed up (versioning on, state pull saved)

  • Code committed on a migration branch

  • tofu init run, lock file diff reviewed and committed

  • tofu plan shows no changes

  • tofu apply done, then one small change planned and applied

  • CI, scripts and wrappers switched to tofu, version pinned

  • terraform removed from shared images and docs updated

  • State encryption enabled in a separate change (optional)

Recap

  • OpenTofu is a Terraform fork under MPL 2.0, governed by the Linux Foundation. It runs the same HCL and uses the same providers through its own registry.

  • The migration is back up, tofu init, tofu plan (no changes), tofu apply, then one small change.

  • OpenTofu reads Terraform state, but not necessarily the other way around. Treat the first apply as a one-way door, and migrate consumers of terraform_remote_state before their producers.

  • State encryption is OpenTofu's strongest differentiator. Add it after the migration, guard your key, and use enforced = true.

  • Before you start, check your version constraints (versions.tofu), the lock file, any HCP Terraform usage and any tooling that still runs terraform.

Migrate boringly first, then get fancy.

Sources


Details checked against the OpenTofu and Terraform documentation on November 18, 2026. The OpenTofu-side snippets (state encryption, .tofu files, version constraints, state pull and push) were run against OpenTofu 1.13.0. Tooling moves quickly, so if a command or behavior differs on your version, the official docs win. Try the demo on a throwaway project before you use it as a template for production.

Comments(0)

Join the discussion by logging into your account.

No comments yet. Be the first to comment!

Bhavya Arora

Passionate developer sharing knowledge about modern web technologies and best practices.

Subscribe to Bhavya Arora's Newsletter

Direct email dispatches when new stories are published. Zero algorithms.