--- title: "Terraform vs OpenTofu in 2026: A Safe Migration Walkthrough" author: "Bhavya Arora" published: "2026-11-18T05:37:05.886Z" updated: "2026-11-18T05:37:05.886Z" url: "https://zyvop.com/terraform-vs-opentofu-in-2026-a-safe-migration-walkthrough-na9jj" canonical: "https://zyvop.com/terraform-vs-opentofu-in-2026-a-safe-migration-walkthrough-na9jj" tags: ["Terraform","infrastructure as code","DevOps","migration","opentofu"] --- # 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. ![Cover image]() 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 ```mermaid 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.
Investigate or roll back"] F --> H["Make one small change
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`: ```hcl 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: ```bash 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: ```bash 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: ```bash terraform state pull > backup/state-before-tofu.json ``` ### Step 2: Install OpenTofu Follow the [install guide]() for your platform, then check it: ```bash tofu --version ``` Keep Terraform installed on your own machine for now. You'll want it for rollback. ### Step 3: Initialize ```bash tofu init ``` This downloads providers from the OpenTofu registry, initializes your backend, and prepares the working directory. Check what changed in the lock file: ```bash 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" ```bash 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 ```bash 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: ```hcl resource "terraform_data" "release" { input = "release-${random_pet.app.id}-v2" } ``` ```bash 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: ```hcl 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**. ```text 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`: ```hcl 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: ```bash 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: ```hcl 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: ```hcl 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: ```hcl # 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: ```bash 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: ```text 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: ```bash 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 - [OpenTofu: Migration Guide]() - [OpenTofu: Migrating interdependent configurations]() - [OpenTofu: State and Plan Encryption]() - [OpenTofu v1.13.0 release post]() - [OpenTofu: What's new in 1.11]() - [OpenTofu FAQ]() - [OpenTofu: Language and compatibility settings]() - [Terraform: lifecycle reference (v1.17.x)]() - [Terraform: for\_each meta-argument (v1.17.x)]() - [Spacelift: HashiCorp's license change]() * * * _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._