Install & Compatibility
Where this runs
tested against v4.1.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.95 runs
installs and imports cleanly · install 0.0s · import 0.216s · 55.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.1s · import 0.216s · 57MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vault
✓ from ansible_vault import Vault
✗ from ansible_vault.vault import Vault
The main `Vault` class is directly accessible from the top-level package.
This quickstart demonstrates how to initialize the `Vault` object with a password, then encrypt and decrypt a simple string. It also shows how to use `Vault.dump()` to write encrypted YAML content to a file and `Vault.load()` to read and decrypt it.
import os
from ansible_vault import Vault
# Get password from environment for security, or provide directly
vault_password = os.environ.get('ANSIBLE_VAULT_PASSWORD', 'your_secret_password').encode()
vault = Vault(vault_password)
# 1. Encrypt and decrypt a string
original_string = 'my_secret_data'
encrypted_string = vault.encrypt(original_string)
decrypted_string = vault.decrypt(encrypted_string)
print(f"Original: {original_string}")
print(f"Encrypted: {encrypted_string[:20]}...") # Truncate for display
print(f"Decrypted: {decrypted_string}")
# 2. Encrypt and decrypt a YAML file
# Create a dummy vault file
file_content = {
'database': {
'host': 'localhost',
'username': 'dbuser',
'password': 'dbpassword123'
},
'api_key': 'supersecretapikey'
}
vault_file_path = 'my_vault.yml'
with open(vault_file_path, 'w') as f:
vault.dump(file_content, f)
print(f"\nVault YAML file '{vault_file_path}' created and encrypted.")
# Load and decrypt the YAML file
with open(vault_file_path, 'r') as f:
decrypted_yaml_content = vault.load(f)
print(f"Decrypted YAML content: {decrypted_yaml_content}")
# Clean up the dummy file
os.remove(vault_file_path)
ansible-vault --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ansible_vault'
The 'ansible-vault' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install ansible-vault'.
AnsibleVaultError: Decryption failed (no vault secrets were found that could decrypt)
The provided vault password does not match the one used to encrypt the data.
fixEnsure you are using the correct vault password that was used during encryption.
ImportError: cannot import name 'VaultLib' from 'ansible.parsing.vault'
The 'ansible.parsing.vault' module is not available or accessible in the current environment.
fixVerify that Ansible is installed correctly and that the module is present in your Python path.
ERROR: ansible-vault requires a newer version of pycrypto than the one installed on your platform
The installed version of the 'pycrypto' library is outdated and incompatible with 'ansible-vault'.
fixUpgrade 'pycrypto' to the latest version using pip: 'pip install --upgrade pycrypto'.
TypeError: expected bytes-like object, not 'str'
A string was passed where a bytes-like object was expected, often due to incorrect handling of vault passwords or encrypted data.
fixEnsure that vault passwords and encrypted data are correctly encoded as bytes objects before processing.
Upgrade
Version history
4.1.0latest on PyPI · released May 15, 2025
Audit
Dependencies
PyYAMLrequiredRequired for YAML parsing and serialization.
cryptographyrequiredProvides the underlying cryptographic primitives for encryption and decryption.
MarkupSaferequiredA dependency, likely for safe string handling or templating, used by `cryptography` or `PyYAML` indirectly.