What is OpenTofu?

OpenTofu is the community-driven answer to Terraform's controversial licensing shift, offering infrastructure engineers a truly open-source alternative with

• better security,
• better state management, and
• better developer-focused features.

It addresses the concerns of terraform users while introducing innovations long requested by the community but never implemented in the original product.

In August 2023, HashiCorp changed Terraform's license from the Mozilla Public License v2.0 (MPL v2.0) to a restrictive Business Source License (BSL), prompting leading companies including Gruntwork, Spacelift, Harness, Env0, and Scalr to create OpenTofu as a fork of the last open-source version. This guide covers everything you need to know about OpenTofu in 2026.

What is OpenTofu?

OpenTofu is a drop-in replacement for Terraform that preserves compatibility with existing configurations while adding significant enhancements. It functions as an Infrastructure as Code (IaC) tool that enables engineers to define infrastructure resources declaratively using HashiCorp Configuration Language (HCL).

Core Capabilities

OpenTofu uses human-readable configuration files to define infrastructure resources declaratively, allowing engineers to express their desired infrastructure state rather than writing procedural scripts. The tool builds a resource graph to determine dependencies and applies changes efficiently.

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  tags = {
    Name = "example-instance"
  }
}

State File Management

A critical aspect of OpenTofu's functionality is state file management. The state file serves as the source of truth that maps configured resources to real-world infrastructure objects and tracks metadata. OpenTofu's state management approach offers several advantages:

• Efficient change detection through state comparison
• Resource dependency tracking for proper ordering of operations
• Performance optimization for large infrastructures
• Secure collaboration through remote state backends

Community and Governance

With over 25,000 GitHub stars and more than 70 active contributors, OpenTofu has established itself as a vibrant open-source project. As a Linux Foundation project, OpenTofu is guided by a Technical Steering Committee representing multiple companies rather than being controlled by a single vendor. The CNCF accepted OpenTofu into its fold in April 2025, further solidifying its position in the cloud-native ecosystem.

Development priorities are shaped by:

• Public issue tracking and feature voting
• An open Request for Comments (RFC) process for major changes
• Weekly community meetings for transparent discussion
• Active Slack channels for real-time collaboration

OpenTofu vs Terraform: Key Differences

While OpenTofu maintains compatibility with Terraform configurations, several key differences have emerged as the projects diverge.

Licensing Model

OpenTofu: Uses the Mozilla Public License v2.0 (MPL v2.0), a true open-source license recognized by the Open Source Initiative. Users can freely use, modify, and distribute the software without ambiguity about competitive restrictions.

Terraform: Licensed under the Business Source License (BSL), a "source-available" license that prohibits using the software in ways that compete with HashiCorp's commercial offerings.

Governance and Development

OpenTofu: Community-driven development under Linux Foundation's neutral governance. Development priorities are set through transparent RFCs and community voting.

Terraform: Controlled by HashiCorp (now IBM), with development priorities set by commercial interests.

Innovative Features

OpenTofu has implemented several features long requested by the community but never added to Terraform:

File Extensions

OpenTofu supports both .tf and .tofu file extensions. When both exist with the same name, OpenTofu prioritizes the .tofu file, enabling module authors to provide OpenTofu-specific functionality while maintaining Terraform compatibility.

Migration Guide: From Terraform to OpenTofu

Migrating from Terraform to OpenTofu is designed to be straightforward. The migration process is a simple binary replacement in most cases.

Step-by-Step Migration

1. Verify Your Current State

Ensure your Terraform state is clean and there are no pending changes:

$ terraform plan
No changes. Your infrastructure matches the configuration.

If there are changes, apply them before proceeding.

2. Back Up Your State File

Always back up your terraform.tfstate file and any remote state before migration. This is critical and non-negotiable.

3. Install OpenTofu

Install the OpenTofu CLI on your machine:

$ brew install opentofu
$ tofu --version
OpenTofu v1.10.0

You can now use the tofu command as a drop-in replacement for terraform.

4. Initialize OpenTofu

Run tofu init upgrade in your project directory. The upgrade flag ensures there are no conflicts with pulling providers from the OpenTofu registry:

$ tofu init upgrade
Initializing the backend...
Initializing provider plugins...

5. Plan and Apply with OpenTofu

Run tofu plan to ensure OpenTofu recognizes your existing infrastructure without planning unexpected changes:

$ tofu plan
No changes. Your infrastructure matches the configuration.

Once confident, run tofu apply to update the state file to the OpenTofu format:

$ tofu apply
No changes. Your infrastructure matches the configuration.
Apply complete!

Version Compatibility Considerations

Migrating from Terraform v1.5.x or lower: Migrate to OpenTofu v1.6.x first, then upgrade to the latest version. OpenTofu v1.6+ is fully compatible with Terraform v1.5.x.

Migrating from Terraform v1.6.x and newer: The migration is straightforward, but be aware of any new features or syntax introduced in later Terraform versions that may not yet be supported by OpenTofu.

Important Considerations

• Provider Sources: By default, OpenTofu uses registry.opentofu.org. If your configurations explicitly use registry.terraform.io, update them to use the OpenTofu registry.
• Tooling and Integrations: Verify compatibility with third-party tools (CI/CD pipelines, linters, security scanners). Most tools supporting older Terraform versions work fine with OpenTofu.
• Module Compatibility: Confirm that any modules you rely on are compatible with OpenTofu.
• Testing: Perform small, non-critical changes first to ensure everything works before making major infrastructure updates.

Advanced OpenTofu Features

State File Encryption

One of OpenTofu's most significant innovations is built-in state file encryption, a feature implemented in version 1.7. This addresses a longstanding security concern in the infrastructure as code community.

Why State Encryption Matters

State files contain sensitive data including database passwords, API keys, and private IPs. While remote backends like S3 offer some protection, client-side encryption provides defense-in-depth security at rest.

Implementing State Encryption

OpenTofu supports multiple key provider options:

terraform {
  encryption {
    key_provider "pbkdf2" "mykey" {
      passphrase = "secure-passphrase"
      key_length = 32
      iterations = 600000
    }
    method "aes_gcm" "default" {
      key_provider = key_provider.pbkdf2.mykey
    }
    state {
      method = method.aes_gcm.default
    }
  }
}

You can also use AWS KMS, GCP KMS, or other external key management services for enterprise deployments.

Dynamic Provider Configurations with for_each

Provider iteration using for_each (added in version 1.9) enables dynamic provider configurations, significantly reducing code duplication for multi-region deployments.

Multi-Region Deployment Pattern

Instead of defining separate provider blocks for each region:

provider "aws" {
  for_each = toset(var.regions)
  alias    = each.key
  region   = each.key
}

resource "aws_instance" "servers" {
  for_each = {
    for region in var.regions : region => {
      instance_type = "t3.micro"
    }
  }

  provider      = aws[each.key]
  ami           = data.aws_ami.ubuntu[each.key].id
  instance_type = each.value.instance_type

  tags = {
    Name = "server-${each.key}"
  }
}

This pattern eliminates repetitive code and makes configurations more maintainable.

Dynamic Backend Blocks

OpenTofu allows backend configurations to use variables and locals, enabling dynamic backend selection based on environment:

terraform {
  backend "s3" {
    bucket  = var.state_bucket
    key     = "${var.environment}/terraform.tfstate"
    region  = var.aws_region
    encrypt = true
  }
}

This enables a single configuration to support multiple deployment environments without code duplication.

Early Variable Evaluation

OpenTofu allows variables, locals, and data sources inside the top-level tofu block and for backend configurations—something Terraform traditionally restricts to static values. This unlocks powerful patterns:

locals {
  environment = var.env
  region      = var.aws_region
}

terraform {
  backend "s3" {
    bucket = "tf-state-${local.environment}"
    key    = "${local.region}/terraform.tfstate"
  }
}

The Native Test Framework

OpenTofu v1.10 introduced a native testing framework, eliminating the need for external test tools. The framework uses .tftest.hcl files:

run "validate_bucket_creation" {
  command = apply

  assert {
    condition     = aws_s3_bucket.main.id == "my-test-bucket"
    error_message = "S3 bucket name does not match expected value"
  }
}

run "validate_encryption_enabled" {
  command = apply

  assert {
    condition     = aws_s3_bucket_server_side_encryption_configuration.main.rules[0].apply_server_side_encryption_by_default[0].sse_algorithm == "AES256"
    error_message = "S3 bucket encryption is not enabled"
  }
}

The test framework supports:

• Multiple test runs with setup/teardown
• State assertions to validate resource creation
• Plan-time and apply-time validation
• Test variables and overrides

Resource Exclusion with the exclude Flag

The exclude flag (v1.9) enables selectively skipping resources during operations. This complements the target flag by providing inverse selection logic:

# Apply all resources except database
tofu apply -exclude 'aws_db_instance.prod'

# Exclude multiple resources
tofu apply \
  -exclude 'aws_db_instance.prod' \
  -exclude 'aws_rds_cluster.analytics'

Use Cases for Exclusion

• Gradual rollouts: Apply changes to non-critical resources first
• Maintenance windows: Skip resources undergoing maintenance
• Manual management: Exclude resources managed outside IaC
• Risk mitigation: Apply low-risk changes while deferring high-risk ones

Debugging OpenTofu Apply Failures

Failed tofu apply operations can halt pipelines and cause frustration. Understanding common failure modes and debugging techniques is essential.

Common Failure Categories

Authentication Errors

When credentials are invalid or expired, providers fail to authenticate:

Error: error configuring Terraform AWS Provider: no valid credential sources for Terraform AWS Provider found.

Resolution:

• Verify AWS credentials are correctly set in environment variables or AWS profiles
• Check IAM permissions for required actions
• Refresh temporary credentials if using session tokens

Provider Issues

Provider errors occur when the provider cannot communicate with the target service:

Error: Failed to update instance: Service returned status 503 (Service Unavailable)

Resolution:

• Check service health dashboards
• Verify network connectivity and firewall rules
• Ensure provider version is compatible with target service API

Resource Configuration Errors

Invalid resource configurations fail during apply:

Error: Invalid or missing attribute: instance_type is required

Resolution:

• Validate HCL syntax with tofu fmt -check
• Review required attributes in provider documentation
• Use tofu console to test variable values

State Conflicts

Multiple concurrent applies can corrupt state:

Error: Error acquiring the state lock

Resolution:

• Use remote backends with state locking (S3 + DynamoDB, or Terraform Cloud)
• Implement CI/CD locking to prevent concurrent applies
• Use tofu force-unlock only as a last resort after verifying no other process holds the lock

Debugging Techniques

Enable Verbose Logging

Set TF_LOG environment variable for detailed debugging:

export TF_LOG=DEBUG
tofu apply

Log levels: TRACE, DEBUG, INFO, WARN, ERROR

Inspect the Plan

Use tofu plan output to understand what will change:

tofu plan -json | jq '.resource_changes[] | select(.change.actions[] == "delete")'

Test with Target

Use the -target flag to apply specific resources:

tofu apply -target 'aws_security_group.main'

This isolates problems to specific resources.

Validate and Format

Catch errors early with validation:

tofu validate
tofu fmt -recursive .

Retrieve Provider Documentation

Consult provider documentation for resource constraints:

tofu providers schema -json | jq '.provider_schemas | keys'

LSP Integration and Developer Experience

OpenTofu supports the Language Server Protocol (LSP), enabling intelligent code completion, syntax highlighting, and error detection in modern text editors.

Supported Editors

• Visual Studio Code: via terraform-ls extension
• Neovim/Vim: via LSP configuration
• JetBrains IDEs: via terraform plugin
• Sublime Text: via LSP client plugins

Benefits of LSP Integration

• Real-time validation: Catch syntax errors before running tofu plan
• Auto-completion: Suggest valid attributes and resource types
• Go to definition: Navigate between modules and variables
• Hover documentation: View resource attributes without opening provider docs
• Refactoring: Safe variable and resource renaming

Configuration Example (VS Code)

{
  "languages": {
    "hcl": {
      "command": "terraform-ls",
      "args": ["serve"],
      "initializationOptions": {
        "backend": "memory",
        "experimentalFeatures": {
          "validateOnSave": true,
          "refactoring": true
        }
      }
    }
  }
}

Provider Ecosystem

OpenTofu maintains full compatibility with existing Terraform providers, ensuring access to thousands of infrastructure providers without modification.

Provider Declaration

Providers are declared in the required_providers block:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

OpenTofu Registry

The OpenTofu Registry at registry.opentofu.org mirrors and extends the Terraform provider ecosystem. All major providers including AWS, Azure, GCP, Kubernetes, and 2000+ others are available.

Community Providers

As an open-source project, OpenTofu also supports community-maintained providers and modules, expanding beyond the HashiCorp provider ecosystem.

Alternatives to Terraform Cloud

With the shift to OpenTofu, many organizations seek alternatives for collaborative infrastructure management.

Commercial Platforms

Scalr: Offers comprehensive OpenTofu support with OPA integration, RBAC, custom hooks, and state management.

env0: Provides native OpenTofu support with advanced RBAC, secrets management, and policy enforcement. Founded by one of the original OpenTofu initiative members.

Spacelift: Delivers enterprise-grade features including multi-IaC workflows, Policy as Code, and self-service infrastructure through Blueprints.

Self-Hosted Options

For teams preferring self-hosted solutions:

• Terrakube: An open-source alternative to Terraform Enterprise
• Terralist: Registry for OpenTofu modules and providers
• Atlantis: Pull request automation for infrastructure changes

Current Development Status (2026)

OpenTofu continues evolving with regular releases. Current version is OpenTofu v1.10+, which includes:

• OCI registry support for modules and providers
• Native S3 state locking without DynamoDB
• Experimental OpenTelemetry tracing
• Enhanced error messages and debugging output
• Improved performance for large state files

The project maintains a transparent roadmap using GitHub milestones, allowing users to see and influence upcoming features.

Best Practices for OpenTofu

1. Enable State Encryption

Always encrypt sensitive state data:

terraform {
  encryption {
    key_provider "pbkdf2" "main" {
      passphrase = var.encryption_passphrase
      key_length = 32
      iterations = 600000
    }
    method "aes_gcm" "default" {
      key_provider = key_provider.pbkdf2.main
    }
    state {
      method = method.aes_gcm.default
    }
  }
}

2. Use Remote State with Locking

Store state remotely with locking enabled:

terraform {
  backend "s3" {
    bucket         = "opentofu-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "opentofu-locks"
  }
}

3. Implement Code Review Workflows

Use version control and CI/CD to review changes:

# In CI/CD pipeline
tofu plan -json > plan.json
# Review plan in PR before applying
tofu apply plan.json

4. Structure Modules Effectively

Organize code into reusable modules with clear interfaces:

├── modules/
│   ├── networking/
│   ├── compute/
│   └── database/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── prod/
└── global/

5. Test Infrastructure Code

Use OpenTofu's native test framework:

run "setup" {
  command = apply

  variables {
    environment = "test"
  }
}

run "validate_security_groups" {
  command = plan

  assert {
    condition     = length(aws_security_group.main.ingress) > 0
    error_message = "Security group must have ingress rules"
  }
}

6. Use the Exclude Flag Strategically

Utilize -exclude for phased rollouts:

# Phase 1: Non-critical resources
tofu apply \
  -exclude 'aws_lambda_function.analytics' \
  -exclude 'aws_cloudwatch_log_group.verbose'

# Phase 2: Critical resources (after verification)
tofu apply

7. Implement Proper Variable Management

Use .tfvars files and environment separation:

# Development
tofu apply -var-file="dev.tfvars"

# Production
tofu apply -var-file="prod.tfvars"

8. Monitor with OpenTelemetry

Enable tracing for performance analysis:

export OTEL_SDK_DISABLED=false
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
tofu apply

The Future of OpenTofu

The OpenTofu community has established a clear trajectory for 2026 and beyond. The acceptance into the CNCF demonstrates institutional support and commitment to long-term stability. Development priorities include:

• Enhanced error messages and debugging output
• Performance improvements for large state files
• Expanded provider ecosystem integration
• Community-contributed features through RFCs
• Improved multi-tenancy support

Conclusion

OpenTofu has successfully established itself as a powerful, community-driven alternative to Terraform. By maintaining compatibility with the existing Terraform ecosystem while introducing innovative features like state encryption, provider iteration, and native testing, OpenTofu offers infrastructure engineers both stability and progress.

The project's commitment to true open-source principles through the Mozilla Public License ensures users can deploy OpenTofu without concerns about licensing ambiguity. Its community-driven development approach means features that actually matter to practitioners take priority over commercial interests.

Whether you're a long-time Terraform user concerned about licensing changes, an organization seeking better security features, or a new infrastructure engineer building cloud infrastructure, OpenTofu provides a compelling option that combines mature infrastructure as code capabilities with open governance and continuous innovation.

The combination of CNCF membership, Linux Foundation governance, and an active developer community positions OpenTofu as the future of open-source infrastructure automation. Start your migration today and join the growing community of engineers building infrastructure the right way.

Last Updated: February 2026 OpenTofu Current Version: v1.10+ Terraform Compatibility: Full compatibility through v1.5.x and newer versions with feature parity