Registry / serialization / pyhocon

pyhocon

JSON →
library0.3.63pypypi✓ verified 26d ago

PyHOCON is a Python parser for the HOCON (Human Optimized Config Object Notation) configuration format. It allows for reading, parsing, and manipulating HOCON configuration files and strings, including support for substitutions, includes, and various data types. The library is actively maintained with irregular but consistent minor releases, currently at version 0.3.63.

pip install pyhocon
INSTALL
IMPORT
SIG · PYHOCON
P
pyhocon
serializationpythonv0.3.63
Install
2.5s avg
Import
367ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.63 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.390s · 20.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.5s · import 0.344s · 21MB
18MB installed
● package 18MB
Code
Verified usage

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

ConfigFactory
from pyhocon import ConfigFactory
Main entry point for parsing HOCON strings and files.
HOCONConverter
from pyhocon import HOCONConverter
Used for converting ConfigTree objects back to HOCON or other formats.
ConfigTree
from pyhocon import ConfigTree
Represents the parsed HOCON configuration as a tree-like dictionary.

This quickstart demonstrates how to parse HOCON configuration from both a string and a file using `ConfigFactory`. It also shows how to use environment variable substitutions and how to convert a parsed configuration back into a HOCON string using `HOCONConverter`.

import os from pyhocon import ConfigFactory, HOCONConverter # Example HOCON string hocon_string = """ app { name = "MyApplication" version = "1.0.0" features = [ { id = 1, enabled = true }, { id = 2, enabled = false } ] environment = ${?ENV_NAME} # Optional environment variable substitution } """ # Parse from a string config_from_string = ConfigFactory.parse_string(hocon_string) print(f"Config from string: {config_from_string.get('app.name')}") # Set an environment variable for substitution demonstration os.environ['ENV_NAME'] = 'production' config_from_string = ConfigFactory.parse_string(hocon_string) print(f"Config environment: {config_from_string.get('app.environment')}") os.environ.pop('ENV_NAME') # Clean up # Create a dummy config file for parsing file_content = """ database { host = "localhost" port = 5432 user = "admin" } """ with open("config.conf", "w") as f: f.write(file_content) # Parse from a file config_from_file = ConfigFactory.parse_file("config.conf") print(f"Config from file: {config_from_file.get('database.host')}") # Convert a ConfigTree back to HOCON string hocon_output = HOCONConverter.to_hocon(config_from_string) print("\nConverted HOCON output:\n", hocon_output) # Clean up dummy file os.remove("config.conf")
Debug
Known issues
gotchaThe `pyparsing` dependency version constraint was updated from `~=2.0` to `>=2,<4` in version `0.3.60`. If your project has a specific older `pyparsing` version pinned or relies on `pyparsing` 3.x series, this change might cause dependency conflicts or unexpected behavior.
fix
Ensure your `pyparsing` dependency is compatible with `>=2,<4`. If conflicts arise, consider upgrading or downgrading `pyparsing` to fit `pyhocon`'s requirements, or using a virtual environment to manage dependencies.
affects: >=0.3.60
gotchaSubstitution resolution logic, especially for complex or nested substitutions, has received multiple fixes and enhancements across minor versions (e.g., 0.3.54, 0.3.58, 0.3.61). Behavior involving environment variables, cross-config resolutions, and override order might differ subtly between versions.
fix
If encountering unexpected substitution behavior, upgrade to the latest version of `pyhocon`. Thoroughly test your configurations, particularly those with complex substitutions or environment variable reliance, after upgrading.
affects: <0.3.61
gotchaIn version `0.3.57`, the logic for resolving package-relative paths was rewritten, and the internal `asset` library was removed. This change might subtly alter how `pyhocon` resolves relative file paths within HOCON `include` directives, especially if you had configurations that relied on specific interpretations of relative paths prior to this version.
fix
Review any HOCON configurations using relative `include` directives after upgrading. Ensure that `pyhocon` can still locate the included files correctly. You might need to adjust relative paths or ensure the working directory is set appropriately for file resolution.
affects: <0.3.57
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyhocon'
The 'pyhocon' library is not installed in the Python environment you are currently using, or there is a typo in the import statement.
fix
Install the package using pip: `pip install pyhocon` or `python -m pip install pyhocon`
pyparsing.ParseException: Expected end of text
This error, often along with 'pyparsing.ParseSyntaxException: Expected "{"', indicates a syntax error in your HOCON configuration file or string, such as unbalanced delimiters, incorrect value formatting, or unsupported constructs (e.g., single quotes for strings).
fix
Carefully review your HOCON configuration for syntax correctness, ensuring all brackets, braces, and quotes are properly matched and that string values are enclosed in double quotes as per HOCON specification.
KeyError: 'your_config_key' / pyhocon.exceptions.ConfigMissingException: 'No configuration setting found for key your_config_key'
You are attempting to access a configuration key (e.g., 'your_config_key') that does not exist in the parsed HOCON configuration object.
fix
Verify that the key path exists in your HOCON configuration. Use `config.get('your_config_key', default_value)` to provide a fallback, or check for key existence with `if 'your_config_key' in config:` before accessing.
AttributeError: 'ConfigSubstitution' object has no attribute 'raw_str'
This error typically arises from an incompatibility between the installed version of `pyhocon` and its `pyparsing` dependency, particularly when handling substitutions or deep copying config objects.
fix
Ensure you have compatible versions of `pyhocon` and `pyparsing` installed. Upgrading `pyhocon` to the latest version, which often includes updates for `pyparsing` compatibility, or explicitly installing a known compatible `pyparsing` version (e.g., `pip install pyparsing<3`) can resolve this.
Upgrade
Version history
0.3.63latest on PyPI · released Mar 20, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
pyhocon — pip install pyhocon · libregistry