HVAC: HashiCorp Vault API Client
raw JSON → 2.4.0 verified Tue May 12 auth: no python install: verified
HVAC is a Python client library for interacting with HashiCorp Vault. It provides a programmatic interface to manage secrets, policies, and authentication methods within a Vault instance. Currently at version 2.4.0, the library maintains an active development status with regular minor releases addressing new Vault features, bug fixes, and dependency updates, alongside occasional major releases for significant breaking changes.
pip install hvac Common errors
error requests.exceptions.SSLError: HTTPSConnectionPool(...) (Caused by SSLError(SSLError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (...)'))) ↓
cause 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.
fix
Provide 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) error hvac.exceptions.Forbidden: 1 error occurred: * permission denied ↓
cause 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.
fix
Ensure 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. error hvac.exceptions.InvalidPath: no handler for route "secret/kv1/mega_secret". route entry not found., on get http://localhost:8200 ↓
cause 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.
fix
Explicitly 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. error ImportError: No module named 'hvac' ↓
cause The `hvac` library is not installed in the Python environment where the script is being executed, or the virtual environment is not correctly activated.
fix
Install the
hvac package using pip: pip install hvac. If using a virtual environment, activate it first. error TypeError: 'Response' object is not subscriptable ↓
cause 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.
fix
Inspect 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. Warnings
breaking hvac 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] ↓
fix Upgrade Python to 3.8+ and ensure Vault server is 1.11.x or later. Review changelog for specific method removals.
breaking The `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] ↓
fix Explicitly specify all parameters for `Client.write_data` to ensure desired behavior, rather than relying on implicit defaults.
deprecated The `certificate` parameter for `create_ca_certificate_role` will no longer accept file paths in `v3.0.0`. [cite: v1.1.0 release notes] ↓
fix Pass certificate data as a string directly, rather than a file path, to `create_ca_certificate_role`.
deprecated The 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] ↓
fix Explicitly set `raise_on_deleted_version=True` or `False` when calling `read_secret_version` to ensure consistent behavior regardless of the upcoming default change.
gotcha For 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()`. ↓
fix Always use `client.secrets.kv.v2.list_secrets(mount_point='your_mount', path='your/path/')` for listing secrets and paths in KV v2 engines.
gotcha Vault 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. ↓
fix Ensure 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`.
gotcha New 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] ↓
fix Update exception handling to catch `VaultPermissionDenied` and `VaultPreconditionFailed` for more specific error management if desired.
gotcha The 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). ↓
fix Ensure 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.
gotcha The `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. ↓
fix Ensure 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.
Install
pip install "hvac[parser]" Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) parser wheel - 0.63s 23.2M
3.10 alpine (musl) parser - - 0.65s 23.1M
3.10 alpine (musl) hvac wheel - 0.63s 22.8M
3.10 alpine (musl) hvac - - 0.67s 22.8M
3.10 slim (glibc) parser wheel 2.7s 0.45s 24M
3.10 slim (glibc) parser - - 0.48s 24M
3.10 slim (glibc) hvac wheel 2.2s 0.45s 23M
3.10 slim (glibc) hvac - - 0.49s 23M
3.11 alpine (musl) parser wheel - 0.78s 25.4M
3.11 alpine (musl) parser - - 0.88s 25.4M
3.11 alpine (musl) hvac wheel - 0.78s 25.0M
3.11 alpine (musl) hvac - - 0.88s 25.0M
3.11 slim (glibc) parser wheel 2.2s 0.69s 26M
3.11 slim (glibc) parser - - 0.68s 26M
3.11 slim (glibc) hvac wheel 2.3s 0.69s 26M
3.11 slim (glibc) hvac - - 0.67s 25M
3.12 alpine (musl) parser wheel - 0.73s 17.2M
3.12 alpine (musl) parser - - 0.77s 17.2M
3.12 alpine (musl) hvac wheel - 0.70s 16.8M
3.12 alpine (musl) hvac - - 0.81s 16.8M
3.12 slim (glibc) parser wheel 2.0s 0.71s 18M
3.12 slim (glibc) parser - - 0.77s 18M
3.12 slim (glibc) hvac wheel 2.0s 0.72s 17M
3.12 slim (glibc) hvac - - 0.73s 17M
3.13 alpine (musl) parser wheel - 0.69s 16.9M
3.13 alpine (musl) parser - - 0.75s 16.8M
3.13 alpine (musl) hvac wheel - 0.67s 16.5M
3.13 alpine (musl) hvac - - 0.78s 16.4M
3.13 slim (glibc) parser wheel 2.1s 0.69s 17M
3.13 slim (glibc) parser - - 0.75s 17M
3.13 slim (glibc) hvac wheel 2.0s 0.68s 17M
3.13 slim (glibc) hvac - - 0.75s 17M
3.9 alpine (musl) parser wheel - 0.60s 22.4M
3.9 alpine (musl) parser - - 0.61s 22.5M
3.9 alpine (musl) hvac wheel - 0.62s 22.1M
3.9 alpine (musl) hvac - - 0.61s 22.1M
3.9 slim (glibc) parser wheel 2.7s 0.55s 23M
3.9 slim (glibc) parser - - 0.52s 23M
3.9 slim (glibc) hvac wheel 2.5s 0.55s 23M
3.9 slim (glibc) hvac - - 0.54s 23M
Imports
- Client
import hvac client = hvac.Client(...)
Quickstart last tested: 2026-04-24
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}")