Install & Compatibility
Where this runs
tested against v6.1.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.030s · 34.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.027s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pyAesCrypt
✓ import pyAesCrypt
encryptFile
✓ import pyAesCrypt
pyAesCrypt.encryptFile(...)
decryptFile
✓ import pyAesCrypt
pyAesCrypt.decryptFile(...)
encryptStream
✓ import pyAesCrypt
pyAesCrypt.encryptStream(...)
decryptStream
✓ import pyAesCrypt
pyAesCrypt.decryptStream(...)
AESCryptException
✓ from pyAesCrypt import AESCryptException
This quickstart demonstrates how to encrypt and decrypt a file using `pyAesCrypt.encryptFile` and `pyAesCrypt.decryptFile`. It creates a dummy text file, encrypts it, decrypts it, prints the decrypted content, and then cleans up the temporary files. Remember to use a strong password and manage it securely.
import pyAesCrypt
import os
# --- Setup (create dummy file) ---
input_file = "data.txt"
encrypted_file = "data.aes"
decrypted_file = "data.txt.out"
password = os.environ.get('AESCRYPT_PASSWORD', 'mySuperSecretPassword123') # Replace with strong password
buffer_size = 64 * 1024 # 64KB
with open(input_file, 'w') as f:
f.write('This is a test message to be encrypted.')
print(f"Original file '{input_file}' created.")
# --- Encryption ---
try:
pyAesCrypt.encryptFile(input_file, encrypted_file, password, buffer_size)
print(f"File '{input_file}' encrypted to '{encrypted_file}'.")
# --- Decryption ---
pyAesCrypt.decryptFile(encrypted_file, decrypted_file, password, buffer_size)
print(f"File '{encrypted_file}' decrypted to '{decrypted_file}'.")
with open(decrypted_file, 'r') as f:
content = f.read()
print(f"Decrypted content: '{content}'")
# Verify content
with open(input_file, 'r') as f_orig, open(decrypted_file, 'r') as f_dec:
if f_orig.read() == f_dec.read():
print("Decryption successful and content matches original.")
else:
print("WARNING: Decrypted content does NOT match original!")
except pyAesCrypt.AESCryptException as e:
print(f"An encryption/decryption error occurred: {e}")
except FileNotFoundError as e:
print(f"File not found error: {e}")
except PermissionError as e:
print(f"Permission error: {e}")
finally:
# --- Cleanup ---
for f in [input_file, encrypted_file, decrypted_file]:
if os.path.exists(f):
os.remove(f)
print(f"Cleaned up '{f}'.")
Debug
Known issues
breakingPublic API exceptions for I/O errors were changed in version 5.0.0. Code catching specific `IOError` types might need to be updated to catch `pyAesCrypt.AESCryptException` or more specific custom exceptions introduced by the library.fixReview error handling code. Replace general `IOError` catches with `pyAesCrypt.AESCryptException` or more specific exception types documented for pyAesCrypt.
affects: >=5.0.0
breakingVersion 6.0.0 introduced an updated password complexity check. Passwords considered weak in newer versions might have worked in older ones, potentially causing `ValueError: Password too weak` during encryption attempts. Additionally, a default buffer size was set, which might slightly alter performance for applications that previously relied on unspecified buffer sizes.fixEnsure all passwords meet modern complexity standards (e.g., length, mixed characters). Explicitly set `bufferSize` if your application requires specific memory usage or performance characteristics.
affects: >=6.0.0
gotchaBy default, `pyAesCrypt` encrypts and decrypts files using the AES Crypt format version 2. If you need to decrypt files created with very old versions of `pyAesCrypt` (0.x.x series), you must explicitly set `pyAesCrypt.AESCryptVersion = 0` *before* attempting decryption, otherwise decryption will likely fail or yield corrupted data.fixFor compatibility with old files, add `pyAesCrypt.AESCryptVersion = 0` before calling decryption functions. Example: `pyAesCrypt.AESCryptVersion = 0; pyAesCrypt.decryptFile(...)`
affects: All versions (when decrypting old files)
gotchaA bug in stream encryption was fixed in version 6.1.1. Users on older 6.x.x versions (e.g., 6.0.0, 6.1.0) might encounter issues with corrupted output when using `encryptStream` or `decryptStream` functions.fixUpgrade `pyaescrypt` to version 6.1.1 or newer to benefit from the stream encryption fix: `pip install --upgrade pyaescrypt`.
affects: 6.0.0, 6.1.0
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'
The input file specified for encryption or decryption does not exist at the given path.
fixVerify the file path and name. Ensure the input file exists before calling `encryptFile` or `decryptFile`.
pyAesCrypt.AESCryptException: BadSignatureException: Wrong password or file corrupted
The provided password does not match the one used during encryption, or the encrypted file is corrupted/not a valid pyAesCrypt file.
fixDouble-check the password. Ensure you are using the correct file and that it hasn't been tampered with. If decrypting old files, consider setting `pyAesCrypt.AESCryptVersion = 0`.
PermissionError: [Errno 13] Permission denied: 'output.aes'
The Python process does not have write permissions to the specified output directory or file.
fixEnsure the directory where the output file is to be created exists and that the current user/process has write permissions to it. Change the output path to a writable location if necessary.
ValueError: Password too weak
Starting from version 6.0.0, pyAesCrypt enforces stricter password complexity rules, and the provided password did not meet them.
fixChoose a stronger password. It should typically be longer, and include a mix of uppercase and lowercase letters, numbers, and special characters.
Upgrade
Version history
6.1.1latest on PyPI · released Nov 11, 2023
Audit
Dependencies
pycryptodomerequiredProvides the underlying cryptographic primitives for AES encryption/decryption.