Hjson is a syntax extension to JSON, designed as a human-friendly configuration file format. It allows for comments, multiline strings, and optional quotes, aiming to reduce common errors made by humans when writing JSON. The Python implementation, `hjson-py`, is based on `simplejson` and is currently at version 3.1.0.
Install & Compatibility
Where this runs
tested against v3.1.0 · 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
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.028s · 18.2MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.024s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
loads
✓ hjson.loads(hjson_string)
Used for parsing Hjson strings into Python objects.
dumps
✓ hjson.dumps(python_object)
Used for converting Python objects into Hjson formatted strings.
dumpsJSON
✓ hjson.dumpsJSON(python_object)
Used for converting Python objects into strict JSON formatted strings (potentially less performant than `simplejson`'s equivalent).
Demonstrates how to parse Hjson strings into Python objects using `hjson.loads()` and how to serialize Python objects into Hjson or strict JSON strings using `hjson.dumps()` and `hjson.dumpsJSON()` respectively.
import hjson
import collections
# Decoding Hjson
hjson_text = '''
{
foo: a # This is a comment
bar: 1
# Multiline string example
description: '''
This is a
multiline string.
'''
}
'''
# Parse Hjson string
data = hjson.loads(hjson_text)
print(f"Decoded Hjson: {data}")
assert data == collections.OrderedDict([
('foo', 'a'),
('bar', 1),
('description', 'This is a\nmultiline string.\n')
])
# Encoding Python object hierarchies to Hjson
python_obj = {'foo': 'text', 'bar': [1, 2], 'nested': {'key': 'value'}}
hjson_output = hjson.dumps(python_obj, indent=2)
print(f"\nEncoded Hjson:\n{hjson_output}")
# Encoding to strict JSON (note: may be less performant than simplejson)
json_output = hjson.dumpsJSON(python_obj, indent=2)
print(f"\nEncoded JSON:\n{json_output}")
hjson --version
Debug
Known issues
gotchaQuoteless strings in Hjson automatically end at the newline. Preceding and trailing whitespace is ignored, and escapes are not supported. Additionally, a quoteless string cannot start with a comment sequence (`#`, `//`, `/*`), as these characters would become part of the string or be misinterpreted.fixFor explicit string content, especially with whitespace, comments, or escapes, always use single or double quotes. Place comments on separate lines before or after the string value.
affects: All versions
gotchaHjson's relaxed syntax can introduce ambiguity, particularly with quoteless strings that resemble booleans or numbers. For example, `true` is parsed as a boolean, but `True` (with a capital 'T') is parsed as a string, because it's not a recognized boolean literal in Hjson.fixBe mindful of Hjson's type inference rules. If strict type control is necessary, explicitly quote string values that could be misinterpreted as other data types.
affects: All versions
gotchaWhen parsing Hjson, if the root object's opening brace `{` is on the same line as its first key-value pair without a preceding newline, the Python parser might error or misinterpret the structure. While not explicitly in official docs as a bug, it's a reported parsing quirk.fixEnsure opening and closing braces for the root object are on separate lines from their content for robust parsing. Example: `{ \n key: value \n }` instead of `{ key: value }`. affects: Potentially all versions, observed in specific parsing scenarios.
deprecatedFor `hjson.dumps()`, the `indent` parameter in versions prior to 2.1.0 accepted an integer, which was then converted to a string of spaces. While still supported for backwards compatibility, it is now recommended to pass a string (e.g., `' '`) for indentation.fixUse a string value for the `indent` parameter, e.g., `indent=' '` for two spaces, or `indent='\t'` for tabs.
affects: < 2.1.0 (integer indent), >= 2.1.0 (string indent preferred)
gotchaHjson allows omitting curly braces `{}` for the root object, similar to YAML, making configuration files simpler. However, this feature might not be universally supported by all third-party Hjson implementations.fixFor maximum portability and compatibility across different Hjson parsers and tools, it is recommended to explicitly include the root braces in your Hjson files.
affects: All versions (support for omitted root braces)
gotchaThe `hjson.dumpsJSON()` function, which converts Python objects to strict JSON, is noted in the documentation to be 'probably not as performant as the `simplejson` version'. If performance is critical for JSON output, consider using `json.dumps` from the standard `json` module or `simplejson.dumps` directly.fixFor optimal performance when serializing to strict JSON, especially large data structures, consider using the `json` module from Python's standard library or `simplejson` directly instead of `hjson.dumpsJSON()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hjson'
The 'hjson' library is not installed in your Python environment or is not accessible within the current environment.
fixInstall the hjson package using pip: `pip install hjson`
hjson.scanner.HjsonDecodeError: Expecting value: line X column Y (char Z)
The input string or file provided to `hjson.loads()` or `hjson.load()` contains invalid Hjson syntax, such as a missing key/value, an unexpected character, or a file that is entirely empty or consists only of comments.
fixEnsure the Hjson input strictly adheres to the Hjson specification, correcting any syntax errors, misplaced characters, or malformed structures. For files intended to be empty, use an explicit empty object `{}`. TypeError: Object of type <ClassName> is not JSON serializable
The Python object you are attempting to serialize with `hjson.dumps()` or `hjson.dump()` contains data types (e.g., sets, custom classes, datetime objects) that Hjson (and JSON) does not natively support for serialization.
fixConvert unsupported data types into JSON-compatible types (e.g., convert a set to a list) or provide a custom `default` function to `hjson.dumps()` to define how these specific types should be serialized.
Audit
Dependencies
simplejsonrequiredThe Python implementation of Hjson is based on simplejson.