{"schemaVersion":"1.0","type":"TechArticle","types":["Article","TechArticle"],"slug":"terraform-vs-opentofu-in-2026-a-safe-migration-walkthrough-na9jj","url":"https://zyvop.com/terraform-vs-opentofu-in-2026-a-safe-migration-walkthrough-na9jj","title":"Terraform vs OpenTofu in 2026: A Safe Migration Walkthrough","subtitle":"Migrate from Terraform to OpenTofu safely: a hands-on walkthrough of state, state encryption, rollback, and the gotchas that trip teams up.","tldr":"Should you move from Terraform to OpenTofu? Compare the two tools, then follow a safe, runnable migration covering state handling, built-in state encryption, rollback and the eight gotchas to check before you switch.","keywords":["Terraform","infrastructure as code","DevOps","migration","opentofu","Tutorial"],"entities":["Bhavya Arora","Terraform","infrastructure as code","DevOps","migration","opentofu","Tutorial","ZyVOP"],"keyTakeaways":["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."],"headings":["TL;DR","How we got here","Terraform vs OpenTofu at a glance","Should you move?","Pre-flight checklist","The migration at a glance","Hands-on: migrate a demo project","Step 0: Create the starting point","Step 1: Back up state and code","Step 2: Install OpenTofu","Step 3: Initialize","Step 4: Plan and look for \"no changes\"","Step 5: Apply","Step 6: Make one small change","State handling in depth","Compatibility goes one way","Remote backends","Multiple configs that read each other's state","State encryption (do it after the migration)","Gotchas","1. required_version means different things in the two tools","2. Registry and lock file changes","3. Don't mix migration and new features","4. Version hops"],"outboundLinks":["https://search.opentofu.org/","https://opentofu.org/docs/intro/install/","https://opentofu.org/docs/intro/migration/migration-guide/","https://opentofu.org/docs/intro/migration/multiple-configurations/","https://opentofu.org/docs/language/state/encryption/","https://opentofu.org/blog/opentofu-1-13-0/","https://opentofu.org/docs/intro/whats-new","https://opentofu.org/faq/","https://opentofu.org/docs/language/settings/","https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle","https://developer.hashicorp.com/terraform/language/meta-arguments/for_each","https://spacelift.io/blog/hashicorps-license-change"],"contentText":"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: Get to a clean Terraform plan. terraform plan should 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\"] --&gt; B[\"Install OpenTofu\"] B --&gt; C[\"tofu init\"] C --&gt; D[\"tofu plan\"] D --&gt; E{\"No changes?\"} E --&gt;|\"Yes\"| F[\"tofu apply\"] E --&gt;|\"No\"| G[\"Stop. Do not apply.&lt;br/&gt;Investigate or roll back\"] F --&gt; H[\"Make one small change&lt;br/&gt;and plan/apply again\"] H --&gt; 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 = \"&gt;= 1.5.0\" required_providers { random = { source = \"hashicorp/random\" version = \"~&gt; 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 &amp;&amp; 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 &gt; 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 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 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 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 = \"&gt;= 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 = \"&gt;= 1.14.0\" } # versions.tofu (read by OpenTofu) terraform { required_version = \"&gt;= 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 = \"&gt;= 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 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 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 &gt; 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-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: Stop using OpenTofu. Restore your state backup if OpenTofu changed the state. Run terraform init and terraform plan. Confirm there are no unexpected changes. 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.","contentHash":"sha256:16991f40f3e236c3a4961d794d1f66cb5bcfd8b44d13b07c284545539d37f4ef","authorName":"Bhavya Arora","authorUrl":"https://zyvop.com/author/bhavya","authorSameAs":[],"category":"Tutorial","tags":["Terraform","infrastructure as code","DevOps","migration","opentofu"],"audience":"Senior software engineers, systems architects, and technical leads working with Tutorial","tone":"Instructional, practical, code-first","readingTimeMinutes":13,"wordCount":3361,"faqs":null,"primaryTopic":"Tutorial","publishedAt":"2026-11-18T05:37:05.886Z","updatedAt":"2026-11-18T05:37:05.886Z","canonicalUrl":"https://zyvop.com/terraform-vs-opentofu-in-2026-a-safe-migration-walkthrough-na9jj"}