Install & Compatibility
Where this runs
tested against v2.4.0.20260731 · 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.428s · 23.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.412s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from hvac import Client
Type stubs are not imported directly; they provide type information for symbols imported from the runtime library (hvac).
VaultError
✓ from hvac.exceptions import VaultError
Type stubs for exceptions and other modules within hvac are provided via types-hvac but imported from the hvac package itself.
This quickstart demonstrates basic `hvac` client initialization and secret interaction with type hints. It requires the `VAULT_ADDR` and `VAULT_TOKEN` environment variables to be set for successful authentication. The `types-hvac` package provides the type information for `Client` and other `hvac` objects, allowing static analysis tools to verify the code's type safety.
import os
from hvac import Client
from hvac.exceptions import VaultError
# Ensure VAULT_ADDR and VAULT_TOKEN environment variables are set
# For example: export VAULT_ADDR='http://127.0.0.1:8200' VAULT_TOKEN='your_root_token'
client: Client | None = None
try:
vault_addr = os.environ.get('VAULT_ADDR', 'http://127.0.0.1:8200')
vault_token = os.environ.get('VAULT_TOKEN', 'your_vault_token')
client = Client(url=vault_addr, token=vault_token)
if client.is_authenticated():
print('Successfully authenticated to Vault.')
# Example: Write a secret
path = 'secret/data/my-application/config'
secret_data = {'username': 'testuser', 'password': 'testpassword'}
client.secrets.kv.v2.create_or_update_secret(path=path, secret=secret_data)
print(f'Secret written to {path}')
# Example: Read a secret
read_response = client.secrets.kv.v2.read_secret_version(path=path)
if read_response and 'data' in read_response and 'data' in read_response['data']:
print(f"Retrieved username: {read_response['data']['data']['username']}")
else:
print('Secret not found or invalid format.')
else:
print('Failed to authenticate to Vault.')
except VaultError as e:
print(f'Vault operation failed: {e}')
except Exception as e:
print(f'An unexpected error occurred: {e}')
finally:
if client:
# Ensure to close the client session if it manages connections
# In hvac, the underlying requests session is usually managed implicitly or can be closed if explicitly created
# For persistent clients, manual session closing might not be strictly necessary, but good practice for short-lived scripts.
pass
# To verify type checking, run a type checker (e.g., mypy, pyright) on this file.
Debug
Known issues
gotchatypes-hvac is purely for static type checking. Installing it does not provide any runtime functionality; it only supplies type definitions for the `hvac` library. You must install `hvac` separately to use the client.fixAlways install the runtime library `hvac` alongside `types-hvac` (e.g., `pip install hvac types-hvac`).
affects: All versions
gotchaThe version of `types-hvac` aims to be compatible with specific major/minor versions of the `hvac` library (e.g., `types-hvac==2.4.0.*` for `hvac==2.4.*`). Using mismatched versions can lead to inaccurate or failing type checks, especially if the `hvac` API changes.fixEnsure that the installed `types-hvac` version closely matches the `hvac` version you are using. Refer to the `types-hvac` PyPI page or typeshed project for compatibility statements. Consider pinning stub versions (e.g., `types-hvac==2.4.0.20260408`) to avoid unexpected type-checking issues on updates.
affects: All versions
breakingWhile `types-hvac` itself doesn't introduce runtime breaking changes, future major versions of `hvac` (e.g., `hvac==3.0.0`) are slated to include breaking changes, such as modifying the `certificate` parameter for `create_ca_certificate_role` and changing the default for `raise_on_deleted_version`.fixBefore upgrading `hvac` to a new major version, consult the `hvac` changelog and `types-hvac` release notes. Adjust your code to accommodate API changes, such as how `create_ca_certificate_role` handles certificates or how deleted secrets are retrieved from KV v2.
affects: hvac>=3.0.0 (and corresponding types-hvac versions)
Upgrade
Version history
2.4.0.20260731latest on PyPI · released Jul 31, 2026
Audit
Dependencies
hvacrequiredtypes-hvac provides type hints for this package; it is required at runtime to use the functionality described.