Install & Compatibility
Where this runs
tested against v? · pip install
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
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KeyStore
✓ from jks import KeyStore
✗ from pyjks import KeyStore
The package is named 'pyjks', but the main module containing the KeyStore class is 'jks'.
KeystoreException
✓ from jks.util import KeystoreException
The base exception for JKS-related errors is found in `jks.util`.
This quickstart demonstrates how to load a Java KeyStore (JKS) file, authenticate with a password, and iterate through its entries. It uses `os.environ.get` for `KEYSTORE_PATH` and `KEYSTORE_PASSWORD` to allow easy configuration via environment variables or fall back to default placeholders. Error handling for `FileNotFoundError` and `jks.util.KeystoreException` is included for common issues like incorrect paths or passwords.
import jks
import os
# --- Configuration ---
# Replace 'path/to/your/keystore.jks' with the actual path to your JKS file.
# For a runnable example, ensure this file exists or temporarily create an empty one.
keystore_path = os.environ.get('PYJKS_KEYSTORE_PATH', 'my_keystore.jks')
# Replace 'your_keystore_password' with the actual password for your JKS file.
# For security, avoid hardcoding passwords in production; use environment variables or a secret management system.
keystore_password = os.environ.get('PYJKS_KEYSTORE_PASSWORD', 'changeit')
# --- Quickstart Code ---
try:
# Attempt to load the keystore from the specified path and password
with open(keystore_path, "rb") as f:
ks = jks.KeyStore.load(f, keystore_password)
print(f"Successfully loaded keystore from: {keystore_path}")
print(f"Keystore type: {ks.ks_type}")
print(f"Number of entries: {len(ks.entries)}")
if not ks.entries:
print("No entries found in the keystore.")
else:
print("\nKeystore Entries:")
for alias, entry in ks.entries.items():
print(f" Alias: {alias}")
print(f" Type: {entry.entry_type}")
if entry.entry_type == 'key':
print(f" Key Algorithm: {entry.algorithm}")
# Further details like certificate chain can be accessed via entry.cert_chain
elif entry.entry_type == 'cert':
print(f" Certificate Subject: {entry.cert.subject.human_friendly}")
# Further details like issuer, validity, etc., are available on entry.cert
except FileNotFoundError:
print(f"Error: Keystore file not found at '{keystore_path}'.")
print("Please replace 'my_keystore.jks' with an actual path or create a dummy JKS file for testing.")
except jks.util.KeystoreException as e:
print(f"Error loading keystore: {e}")
print("This often indicates an incorrect password or a corrupted/unsupported JKS format.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
error: Microsoft Visual C++ 14.0 is required. Get it with "Microsoft Visual C++ Build Tools"
This error occurs on Windows when installing pyjks (or its dependencies) because some of its underlying cryptographic libraries have C extensions that require a C++ compiler to be present on the system.
fixDownload and install the "Desktop development with C++" workload from Visual Studio Build Tools. Ensure that 'MSVC vxxx - VS 2019 C++ build tools', 'Windows 10 SDK (latest version)', and 'C++/CLI support for build tools' are selected during installation. After installation and a reboot, run `pip install pyjks` again.
ValueError: Hash mismatch; incorrect password or data corrupted
This error typically indicates that the provided password for loading the keystore is incorrect, or the JKS/JCEKS file itself is corrupted or malformed.
fixDouble-check the keystore password for accuracy, including any leading/trailing spaces or case sensitivity. If you are certain the password is correct, the keystore file might be damaged, or it could be an unsupported keystore type. Ensure the `pyjks` version supports the specific JCEKS features used if applicable, as older versions had limitations.
jks.util.BadKeystoreFormatException: Not a JKS or JCEKS keystore (magic number wrong; expected FEEDFEED or CECECECE)
This error means that the file being loaded does not have the expected 'magic number' at its beginning, which signifies a valid JKS or JCEKS keystore format. It often happens when trying to open a PKCS12 (.p12) file or a corrupted file.
fixVerify that the file you are attempting to load is indeed a standard JKS or JCEKS file. PyJKS does not directly support PKCS12 files; for those, you would typically use `OpenSSL.crypto.load_pkcs12` (from the `pyOpenSSL` library) instead.
jks.util.NotYetDecryptedException
This exception occurs when you try to access attributes (like `private_key` or `cert`) of a key entry that has not yet been successfully decrypted. By default, `jks.KeyStore.load()` attempts to decrypt keys using the store password, but if a key has a different password, it remains encrypted.
fixAfter loading the keystore, iterate through the entries and explicitly call the `decrypt()` method on any `PrivateKeyEntry` or `SecretKeyEntry` using its specific password. For example: `entry.decrypt(key_specific_password)`. Alternatively, ensure `try_decrypt_keys=True` is passed to `KeyStore.load()` if all key entries share the store password.
ModuleNotFoundError: No module named 'pyjks'
Despite a successful `pip install pyjks`, this error can occur if Python is being run from a different environment (e.g., a different virtual environment, or the system Python if installed in a virtual environment) where `pyjks` is not installed.
fixEnsure you are activating and running Python from the same virtual environment (if used) where `pyjks` was installed. For example, after `source venv/bin/activate` (Linux/macOS) or `venv\Scripts\activate` (Windows), then run your Python script. Verify installation with `pip list | grep pyjks` in the active environment.
Upgrade
Version history
20.0.0latest on PyPI · released Apr 19, 2020
Audit
Dependencies
cryptographyrequiredProvides cryptographic primitives for handling keys and certificates, including AES, RSA, and SHA operations.