Install & Compatibility
Where this runs
tested against v2.1.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.010s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Properties
✓ from jproperties import Properties
This quickstart demonstrates how to create a `.properties` file, load its contents into a `jproperties.Properties` object, access property values (including their associated metadata), modify and add new properties, and then store the updated properties back to a file. It highlights the use of `iso-8859-1` encoding, which is common for Java properties files.
import os
from jproperties import Properties
# 1. Define a .properties file content
props_content = '''\
# My Application Configuration
app.name=MyApp
app.version=1.0.0
app.env=development
# _some_meta=value
db.host=localhost
db.port=5432
'''
# 2. Write it to a temporary file
prop_file_path = "config.properties"
with open(prop_file_path, "wb") as f:
# jproperties expects bytes, often iso-8859-1 for Java properties
f.write(props_content.encode('iso-8859-1'))
# 3. Load the properties
p = Properties()
with open(prop_file_path, "rb") as f:
p.load(f, "iso-8859-1") # Specify encoding, defaults to iso-8859-1
# 4. Access values
app_name, app_name_meta = p["app.name"]
print(f"App Name: {app_name} (Metadata: {app_name_meta})")
db_host, db_host_meta = p["db.host"]
print(f"DB Host: {db_host} (Metadata: {db_host_meta})")
# 5. Modify / Add properties (with metadata)
p["app.version"] = "1.1.0", {"last_updated": "2026-04-10"}
p["new.setting"] = "some_value"
# 6. Store properties to a new file (including metadata)
out_prop_file_path = "config_updated.properties"
with open(out_prop_file_path, "wb") as f:
p.store(f, "Updated Configuration", timestamp=False, strip_meta=False)
print(f"\nUpdated configuration written to: {out_prop_file_path}")
# Clean up temporary files
os.remove(prop_file_path)
os.remove(out_prop_file_path)
Debug
Known issues
breakingVersion 2.1.2 is the last version to support Python 2.7. Subsequent versions (post 2.1.2) drop support for Python versions older than 3.8. Ensure your Python environment meets the required version for the specific `jproperties` release you are using.fixUpgrade to Python 3.8 or newer, or pin `jproperties<2.1.3` for Python 2.7 compatibility.
affects: >=2.1.3 (implicitly, based on changelog stating post-2.1.2 drops support)
gotchaThe `store()` method, by default, does not write out metadata associated with properties. To include metadata in the output file, you must explicitly set `strip_meta=False` when calling `store()`.fixWhen calling `p.store(file_obj, comments, strip_meta=False)`, ensure `strip_meta=False` is passed if metadata persistence is desired.
affects: All versions
gotchaDirectly modifying or deleting key-value pairs via the internal `prop_obj.properties` dictionary (e.g., `del prop_obj.properties[key]`) will NOT remove any associated metadata. To ensure metadata is also removed, always use the dictionary-like access on the `Properties` object itself (e.g., `del prop_obj[key]`).fixUse `del prop_obj[key]` to delete a property and its metadata, or `prop_obj[key] = value` or `prop_obj[key] = value, metadata` to set values with or without updating metadata.
affects: All versions
gotchaThe `jproperties` library does not support the XML property file format used by Java's `Properties` class. It specifically targets the plain text `.properties` file format. If you need XML support, consider alternative libraries like `javaproperties`.fixUse the plain text `.properties` format or choose a different library (e.g., `javaproperties`) if XML format is required.
affects: All versions
gotchaWhen iterating over a `Properties` object (e.g., `for key in p:`), only the keys are returned. Associated metadata is not included. To retrieve metadata for a specific key, you must access it using `value, metadata = p[key]` or `p.getmeta(key)`.fixUse `value, metadata = p[key]` for paired access or `p.getmeta(key)` to retrieve metadata explicitly.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jproperties'
The 'jproperties' library is not installed in your Python environment.
fixInstall the library using pip: `pip install jproperties`
TypeError: can't concat str to bytes
This error typically occurs when trying to load a properties file opened in text mode ('rt') with the 'jproperties' load method, which expects a file-like object opened in binary mode ('rb') because it handles byte streams for encoding/decoding.
fixOpen the .properties file in binary read mode ('rb') when loading it: `with open('your.properties', 'rb') as f: p.load(f)` jproperties.ParseError: Parse error in <filename>:<line_number>: <error_message>
The .properties file contains invalid syntax or an unexpected format that 'jproperties' cannot parse according to the Java .properties file specification.
fixReview the specified line number in your .properties file to correct any syntax errors (e.g., unescaped special characters, malformed key-value pairs, incorrect line continuations). Ensure the file adheres to the Java .properties file format.
KeyError: '<key_name>'
You are attempting to access a property using a key that does not exist in the loaded 'Properties' object.
fixEnsure the key exists in the properties file and is correctly spelled. You can check for a key's existence using `if 'your_key' in p:` or use the `get()` method with a default value: `value = p.get('your_key', 'default_value')`. Upgrade
Version history
2.1.2latest on PyPI · released Jul 21, 2024
Audit
Dependencies
No dependency data recorded yet.