Install & Compatibility
Where this runs
tested against v2.4.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.910 runs
installs and imports cleanly · install 0.0s · import 0.445s · 23.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.3s · import 0.402s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import hvac
client = hvac.Client(...)
The primary interaction with Vault is through an instance of the hvac.Client class.
This quickstart demonstrates how to initialize the `hvac.Client`, authenticate using a token (read from an environment variable), and perform basic CRUD operations (create, read, delete) on a KV v2 secret engine. Ensure a Vault server is running and accessible at `VAULT_ADDR` with a valid `VAULT_TOKEN` for authentication. The KV v2 secret engine should be enabled at the `secret` mount point.
import os
import hvac
# Configure these environment variables or replace with direct values
VAULT_ADDR = os.environ.get('VAULT_ADDR', 'http://127.0.0.1:8200')
VAULT_TOKEN = os.environ.get('VAULT_TOKEN', 'root-token-for-dev')
try:
client = hvac.Client(url=VAULT_ADDR, token=VAULT_TOKEN)
if not client.is_authenticated():
raise Exception("HVAC client not authenticated. Check VAULT_ADDR and VAULT_TOKEN.")
print("Client authenticated successfully.")
# Example: Write a secret to KV v2 engine
mount_point = 'secret'
path = 'my-app/config'
secret_data = {'api_key': 'super-secret-key-123', 'environment': 'dev'}
print(f"\nWriting secret to {mount_point}/{path}...")
client.secrets.kv.v2.create_or_update_secret(
mount_point=mount_point,
path=path,
secret=secret_data,
)
print("Secret written.")
# Example: Read the secret from KV v2 engine
print(f"\nReading secret from {mount_point}/{path}...")
read_response = client.secrets.kv.v2.read_secret_version(
mount_point=mount_point,
path=path
)
retrieved_data = read_response['data']['data']
print(f"Retrieved secret: {retrieved_data}")
# Example: Delete the secret
print(f"\nDeleting secret {mount_point}/{path}...")
client.secrets.kv.v2.delete_metadata_and_all_versions(
mount_point=mount_point,
path=path
)
print("Secret deleted.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakinghvac v2.0.0 dropped support for Python 3.6 and 3.7. It also removed support for Vault versions 1.6.x through 1.10.x and previously deprecated methods and code paths. [cite: 2.0.0 release notes]fixUpgrade Python to 3.8+ and ensure Vault server is 1.11.x or later. Review changelog for specific method removals.
affects: >=2.0.0
breakingThe `Client.write_data` method's default behavior changed in `v2.1.0` related to a bug fix for a 'potentially dangerous default.' This could alter behavior for users relying on previous default parameters. [cite: 2.1.0 release notes]fixExplicitly specify all parameters for `Client.write_data` to ensure desired behavior, rather than relying on implicit defaults.
affects: >=2.1.0
deprecatedThe `certificate` parameter for `create_ca_certificate_role` will no longer accept file paths in `v3.0.0`. [cite: v1.1.0 release notes]fixPass certificate data as a string directly, rather than a file path, to `create_ca_certificate_role`.
affects: v1.1.0 - <3.0.0
deprecatedThe default value of `raise_on_deleted_version` is planned to change from `True` to `False` in a future major release, impacting how deleted secret versions are handled during reads. [cite: v1.1.0 release notes]fixExplicitly set `raise_on_deleted_version=True` or `False` when calling `read_secret_version` to ensure consistent behavior regardless of the upcoming default change.
affects: v1.1.0 - <future_major_release>
gotchaFor KV v2 secret engines, the generic `client.list()` method does not work as expected for listing paths/folders. You must use `client.secrets.kv.v2.list_secrets()`.fixAlways use `client.secrets.kv.v2.list_secrets(mount_point='your_mount', path='your/path/')` for listing secrets and paths in KV v2 engines.
affects: All versions with KV v2 support
gotchaVault currently defaults the `secret/` path to KV secrets engine version 2 in 'dev' mode. Outside of 'dev' mode (from Vault v1.1.0 onwards), no KV secrets engine is mounted by default at `secret/` and must be explicitly enabled.fixEnsure the KV secrets engine is explicitly enabled and configured at your desired mount point in production Vault environments before attempting to interact with it via `hvac`.
affects: Vault >=1.1.0
gotchaNew exception types (`hvac.exceptions.VaultPermissionDenied` for 405 and `hvac.exceptions.VaultPreconditionFailed` for 412) were added in v2.2.0. If you were catching generic exceptions for these HTTP status codes, your error handling might need updates. [cite: v2.2.0 release notes, 18]fixUpdate exception handling to catch `VaultPermissionDenied` and `VaultPreconditionFailed` for more specific error management if desired.
affects: >=2.2.0
gotchaThe hvac client failed to establish a connection to the Vault server. This typically occurs if the Vault server is not running, is inaccessible, or is listening on a different address/port than configured in the hvac client (default: http://127.0.0.1:8200).fixEnsure the Vault server is running and accessible from the hvac client's environment, and that the client's VAULT_ADDR environment variable or Client initialization parameters correctly specify the Vault server's address and port.
affects: All versions
gotchaThe `hvac` client requires a running Vault server to connect. A `Connection refused` error (e.g., `NewConnectionError` or `Max retries exceeded`) indicates the client could not establish a connection to the configured Vault address (default: `http://127.0.0.1:8200`). This is typically an environment setup issue.fixEnsure your Vault server is running and accessible from where the `hvac` client is executed. Verify the `VAULT_ADDR` environment variable or the `url` parameter in `hvac.Client()` is correctly configured to point to your Vault instance.
affects: All versions
Errors
Common errors & fixes
requests.exceptions.SSLError: HTTPSConnectionPool(...) (Caused by SSLError(SSLError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (...)')))
The Python client cannot verify the authenticity of the Vault server's TLS certificate, often because a self-signed certificate is used or the necessary CA certificate bundle is not provided.
fixProvide the path to the CA certificate bundle using the `verify` parameter, or set `verify=False` for testing (not recommended for production). Example: `client = hvac.Client(url='https://vault.example.com:8200', verify='/path/to/ca_certs.pem')` or `client = hvac.Client(url='https://vault.example.com:8200', verify=False)`
hvac.exceptions.Forbidden: 1 error occurred: * permission denied
The authenticated Vault token does not have the necessary permissions (policies) to perform the requested operation on the specified path in Vault, or a Vault Enterprise namespace is not correctly specified.
fixEnsure the Vault token has a policy attached that grants the required capabilities (e.g., `read`, `list`, `create`, `update`, `delete`) on the target path, and if using Vault Enterprise, explicitly pass the `namespace` parameter to the `hvac.Client` constructor or relevant method.
hvac.exceptions.InvalidPath: no handler for route "secret/kv1/mega_secret". route entry not found., on get http://localhost:8200
This error often occurs when interacting with a KV secrets engine (especially KV v2) without correctly specifying the `mount_point` or if the path structure (e.g., missing `/data/` for KV v2) is incorrect for the Vault API.
fixExplicitly provide the `mount_point` parameter when using `client.secrets.kv.v2.read_secret` or `client.secrets.kv.v1.read_secret`, and ensure the `path` argument is relative to the mount point and includes `/data/` for KV v2 secrets.
ImportError: No module named 'hvac'
The `hvac` library is not installed in the Python environment where the script is being executed, or the virtual environment is not correctly activated.
fixInstall the `hvac` package using pip: `pip install hvac`. If using a virtual environment, activate it first.
TypeError: 'Response' object is not subscriptable
The `hvac` client method returned a raw `requests.Response` object instead of a parsed dictionary, typically when an API call fails (e.g., due to an incorrect path or permissions) or when the response structure is not as expected. It can also indicate an issue with namespace handling in Vault Enterprise.
fixInspect the `requests.Response` object (e.g., `response.status_code`, `response.text`) to understand the underlying HTTP error before attempting to access dictionary keys. If using Vault Enterprise, verify the `namespace` parameter is correctly passed to the `hvac.Client` constructor.
Upgrade
Version history
2.4.0latest on PyPI · released Oct 30, 2025
Audit
Dependencies
PythonrequiredRequired for execution