Python HCL2
A parser for HCL2 written in Python using
Lark. It can be used as a Python library or through its CLI tools:
hcl2tojson, jsontohcl2, and hq — a jq-like query tool for HCL files.
Supports HCL2 only (not backwards compatible with HCL v1) and works with any HCL2 config file such as Terraform.
About Amplify
Amplify builds innovative and compelling digital educational products that empower teachers and students across the country. We have a long history as the leading innovator in K-12 education - and have been described as the best tech company in education and the best education company in tech. While others try to shrink the learning experience into the technology, we use technology to expand what is possible in real classrooms with real students and teachers.
Learn more at https://www.amplify.com
Getting Started
Prerequisites
python-hcl2 requires Python 3.8 or higher to run.
Installing
This package can be installed using pip
pip3 install python-hcl2
To install the CLI tools (hcl2tojson, jsontohcl2, hq) globally without affecting your project environments, use pipx:
pipx install python-hcl2
Usage
HCL2 to Python dict:
import hcl2
with open("main.tf") as f:
data = hcl2.load(f)
Python dict to HCL2:
import hcl2
hcl_string = hcl2.dumps(data)
with open("output.tf", "w") as f:
hcl2.dump(data, f)
Building HCL from scratch:
import hcl2
doc = hcl2.Builder()
res = doc.block("resource", labels=["aws_instance", "web"], ami="abc-123", instance_type="t2.micro")
res.block("tags", Name="HelloWorld")
hcl_string = hcl2.dumps(doc.build())
Documentation
| Guide | Contents |
|---|---|
| Getting Started | Installation, load/dump, options, CLI converters |
| Querying HCL (Python) | DocumentView, BlockView, tree walking, view hierarchy |
| Advanced API | Pipeline stages, Builder |
| hq Reference | hq CLI — structural queries, hybrid/eval, introspection |
| hq Examples | Real-world queries for discovery, compliance, extraction |
| Migrating to v8 | Breaking changes, updated API patterns, v7-compat options |
CLI Tools
python-hcl2 ships three command-line tools:
# HCL2 → JSON
hcl2tojson main.tf # prints JSON to stdout
hcl2tojson main.tf output.json # writes to file
hcl2tojson terraform/ output/ # converts a directory
# JSON → HCL2
jsontohcl2 output.json # prints HCL2 to stdout
jsontohcl2 output.json main.tf # writes to file
jsontohcl2 output/ terraform/ # converts a directory
# Query HCL2 files
hq 'resource.aws_instance.main.ami' main.tf
hq 'variable[*]' variables.tf --json
All commands accept - as PATH to read from stdin. Run --help on any command for the full list of flags.
Building From Source
For development, tox>=4.0.9 is recommended.
Running Tests
python-hcl2 uses tox. You will need to install tox with pip install tox.
Running tox will automatically execute linters as well as the unit tests.
You can also run them individually with the -e argument.
For example, tox -e py310-unit will run the unit tests for python 3.10
To see all the available options, run tox -l.
Releasing
To create a new release go to Releases page, press 'Draft a new release', create a tag with a version you want to be released, fill the release notes and press 'Publish release'. Github actions will take care of publishing it to PyPi.
Roadmap
Planned features, roughly in priority order:
- MCP server — expose parsing, querying, and formatting as MCP tools for AI agents
- Predictable formatting — source-derived formatting heuristics and stable whitespace defaults
- In-place tree edits —
hq set,hq deletefor programmatic HCL modification - Comment deserialization — comments survive JSON round-trips and tree edits
- Expression intelligence — variable reference tracking, unused variable detection, cross-file analysis
- Refactoring operations —
hq rename,hq extract-module,hq sortfor high-level code transforms
Responsible Disclosure
If you have any security issue to report, contact project maintainers privately. You can reach us at mailto:github@amplify.com
Contributing
We welcome pull requests! For your pull request to be accepted smoothly, we suggest that you:
- For any sizable change, first open a GitHub issue to discuss your idea.
- Create a pull request. Explain why you want to make the change and what it's for.
We'll try to answer any PR's promptly.
Limitations
None that are known.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file python_hcl2-8.1.3.tar.gz.
File metadata
- Download URL: python_hcl2-8.1.3.tar.gz
- Upload date:
- Size: 118.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bee7cc697144ac9113a0a29cee22a7cb6c0aa0ba043f2f19040c71d07820044d
|
|
| MD5 |
4eaf92f4fbd8607bc63981f34699ef04
|
|
| BLAKE2b-256 |
84e0c0bd414505d4c8a70d453d4c9d278b9d9dcf256a82f2c01be56cc0c3ee10
|
File details
Details for the file python_hcl2-8.1.3-py3-none-any.whl.
File metadata
- Download URL: python_hcl2-8.1.3-py3-none-any.whl
- Upload date:
- Size: 102.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1770376ec6a16f4991aba4fcb3bc6f21f018ff47856d5332f152773341eb2c78
|
|
| MD5 |
7f84615ac6ed7bf30708d95b8e8a77e1
|
|
| BLAKE2b-256 |
d76898c578b481b83ed1963c92fd148fbde425c1eabb37c417d370858352fb29
|
