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

Execution model: TerraformCommand and AsyncTerraformCommand use process-isolated execution by default, so Terraform's process-wide state does not leak into the caller process. Use backend="thread" only when you explicitly want the current-process backend. Use TerraformPool when you want to reuse worker processes or run independent Terraform operations in parallel.

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 reuse worker processes and run Terraform commands in parallel:

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.