
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
terraformbinary fortofuand checking thattofu planshows 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_stateordering, HCP Terraform, and CI tooling that still callsterraform.
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 |
|
|
Providers | Terraform Registry | Same providers, separate registry ( |
State encryption | Not built in; you rely on backend encryption or external tools | Built in since 1.7, for state and plan files |
| Not available in regular configurations (only in Stacks) | Since 1.9 |
Ephemeral values and write-only attributes | Available | Available since 1.11 |
| 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_eachor theenabledmeta-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:
Get to a clean Terraform plan.
terraform planshould show no changes. Switching tools with pending changes is a bad idea.Standardize versions. If your configs run different Terraform versions, bring them to the same version first. It narrows down what could go wrong.
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.)Check your providers and modules. Search for each at search.opentofu.org. Most are there, but a missing one will stop
tofu init.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.Check whether you use HCP Terraform (Terraform Cloud). That is a bigger migration. See the gotchas below.
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 changesStep 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.jsonStep 2: Install OpenTofu
Follow the install guide for your platform, then check it:
tofu --versionKeep Terraform installed on your own machine for now. You'll want it for rollback.
Step 3: Initialize
tofu initThis 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.hclYou 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 planYou 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 applyEven 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 applyAn 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 applyagainst 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 BThe 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 applyOpenTofu 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
fallbackblock when you change keys, or setencrypted_metadata_aliason 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 = truein code if you pass encryption config through theTF_ENCRYPTIONenvironment 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 aremote_state_data_sourcesblock so it can decrypt it.Know the way back. To return to unencrypted state, reverse the process: make the
unencryptedmethod primary and move your old method intofallback. 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_arm64Source addresses that explicitly point to
registry.terraform.iomay need updating.If a provider or module isn't in the OpenTofu registry,
tofu initfails 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 it4. 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 owncloudbackend that requires an explicithostnameand 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 changesTreat 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-opentofuaction 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
tofubinary (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:
Stop using OpenTofu.
Restore your state backup if OpenTofu changed the state.
Run
terraform initandterraform plan.Confirm there are no unexpected changes.
Carry on with Terraform.
Where you are | Can you roll back? |
|---|---|
Before the first | 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 planis clean on every root moduleAll configs on the same Terraform version
Providers and modules checked at search.opentofu.org
Version constraints sorted:
versions.tffor Terraform,versions.tofufor OpenTofuDependency graph mapped,
terraform_remote_stateorder decided (consumers first)State backed up (versioning on,
state pullsaved)Code committed on a migration branch
tofu initrun, lock file diff reviewed and committedtofu planshows no changestofu applydone, then one small change planned and appliedCI, scripts and wrappers switched to
tofu, version pinnedterraformremoved from shared images and docs updatedState 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_statebefore 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 runsterraform.
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!