bc-python-hcl2

library0.4.3pypypi✓ verified 24d ago

bc-python-hcl2 is a Python library that provides a parser for HashiCorp Configuration Language 2 (HCL2). It is written in Python using Lark and can be used to parse any HCL2 configuration file, such as Terraform files. This package, currently at version 0.4.3, is a fork of the original `python-hcl2` by Amplify and is officially supported by Bridgecrew. The two projects are diverging, so it's important to be aware of which specific package is being used.

devops

pip install bc-python-hcl2

github ↗package ↗

INSTALL

IMPORT

SIG · BC-PYTHON-HCL2

bc-python-hcl2

devopspythonv0.4.3

Install

1.7s avg

Import

2848ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 2.968s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 2.728s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hcl2

✓ import hcl2

✗ from bc_python_hcl2 import hcl2

The primary interface is directly through the `hcl2` module, not a submodule of `bc_python_hcl2`.

This quickstart demonstrates how to parse HCL2 content from a file into a Python dictionary using `hcl2.load()`.

import hcl2 import os hcl_content = ''' variable "region" { description = "AWS region" type = string default = "us-east-1" } resource "aws_s3_bucket" "example" { bucket = "my-unique-example-bucket-123" tags = { Name = "My bucket" Environment = "Dev" } } ''' # Create a dummy HCL file with open('example.tf', 'w') as f: f.write(hcl_content) # Load HCL from a file with open('example.tf', 'r') as f: parsed_hcl = hcl2.load(f) print(parsed_hcl) # Clean up the dummy file os.remove('example.tf')

Debug

Known issues

gotchaThis library (`bc-python-hcl2` by Bridgecrew) is a fork of `python-hcl2` by Amplify Education. While they share a common history, they are now diverging. Ensure you are using the correct package based on your project's needs, as their APIs or behaviors may differ in future versions.

fix

Explicitly install `bc-python-hcl2` if you intend to use the Bridgecrew-maintained fork, and consult its specific documentation for API nuances. If your project relies on the Amplify Education version, install `python-hcl2`.

affects: All versions

breakingThe library explicitly supports HCL2 only and is not backwards compatible with HCL v1. Attempting to parse HCL v1 syntax will result in errors.

fix

Ensure that all HCL configuration files you intend to parse adhere strictly to the HCL2 specification. For HCL v1, a different parser would be required.

affects: All versions

gotchaOlder versions or information might suggest `python-hcl2` is a read-only parser. However, current versions (including `bc-python-hcl2` 0.4.3) support writing/reconstructing HCL2 from Python dictionaries using `hcl2.dumps()`, `hcl2.dump()`, and `hcl2.Builder()`.

fix

Refer to the latest documentation for `hcl2.dumps()`, `hcl2.dump()`, and `hcl2.Builder()` to leverage HCL2 writing capabilities.

affects: <0.4.0 (for bc-python-hcl2), <6.x (for upstream python-hcl2)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hcl2'

The Python interpreter cannot find the 'hcl2' module, most commonly because the `bc-python-hcl2` package was not installed, or there's an environment issue, or a conflict with the upstream `python-hcl2` package.

fix

Ensure `bc-python-hcl2` is installed in your active environment using `pip install bc-python-hcl2`. If you have `python-hcl2` also installed, consider uninstalling it or using a dedicated virtual environment.

ImportError: cannot import name 'START_LINE' from 'hcl2' (unknown location)

This error occurs when a specific symbol (like `START_LINE`) expected from the `hcl2` module is not found, often due to a version mismatch between `bc-python-hcl2` and code expecting a different version of `hcl2`, or due to conflicts if both `bc-python-hcl2` and `python-hcl2` are present.

fix

Ensure you have the correct and most up-to-date `bc-python-hcl2` installed (`pip install --upgrade bc-python-hcl2`). If `python-hcl2` is also installed, remove it to prevent conflicts (`pip uninstall python-hcl2`). Using a dedicated virtual environment is highly recommended.

KeyError: '__ANON_3'

This is a low-level parsing error from the underlying Lark parser used by `bc-python-hcl2`, indicating that the HCL2 input file contains a syntax that the parser does not expect or cannot handle, often with complex expressions like conditional statements.

fix

Review the HCL2 file for syntax errors, especially around conditional statements, string interpolations, or unusual HCL2 constructs. Simplify complex HCL2 expressions if possible, or report the specific HCL2 snippet as an issue to the `bc-python-hcl2` repository if it seems to be a parser limitation.

Upgrade

Version history

0.4.3latest on PyPI · released Jul 14, 2025

Audit

Dependencies

larkrequiredCore parsing engine for HCL2 grammar.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/bridgecrewio/python-hcl2 ↗

packagehttps://pypi.org/project/bc-python-hcl2/ ↗