Python libterraform

Python binding for Terraform. Bundles Terraform as a shared library so you can run Terraform commands and parse configurations from Python without a separate terraform binary.

Language: English | 中文

Documentation: https://prodesire.github.io/py-libterraform/

Installation

pip install libterraform

Threading: TerraformCommand can be called from multiple Python threads, but Terraform CLI execution is serialized inside the shared library because Terraform uses process-wide state. Use TerraformPool (or separate processes) if you need truly parallel Terraform operations.

Usage

from libterraform import TerraformCommand, TerraformConfig

# Run Terraform commands
cli = TerraformCommand("path/to/module")
cli.init(check=True)
cli.plan(check=True)

# Parse Terraform configuration
module, diagnostics = TerraformConfig.load_config_dir("path/to/module")

Asyncio applications can use AsyncTerraformCommand to await Terraform operations without blocking the event loop:

from libterraform import AsyncTerraformCommand

cli = AsyncTerraformCommand("path/to/module")
await cli.validate(check=True)

Use TerraformPool to run Terraform commands in parallel across worker processes:

from libterraform import TerraformPool

with TerraformPool(max_workers=4) as pool:
    for result in pool.map("validate", ["modules/a", "modules/b"], check=True):
        print(result.value["valid"])

The pool starts worker processes, so this must run under an if __name__ == "__main__": guard. The Quick Start creates a runnable module in seconds, and Parallel Execution has a complete pool example.

If you are choosing between Python Terraform options, see Choosing a Python Terraform Integration for a comparison with python-terraform, TofuPy, direct subprocess, Pulumi, CDKTN, and deprecated CDK for Terraform.

Contributing

Install uv, then:

make install        # Install dependencies and Git hooks
make build          # Build the shared library
make test           # Run tests
make lint           # Run linters
make doc-serve      # Preview documentation site

See the Development Guide for details.