PyCryptodomeX

raw JSON →
3.23.0 verified Tue May 12 auth: no python install: verified quickstart: verified

PyCryptodomeX is a self-contained Python package providing low-level cryptographic primitives. It is a fork of the unmaintained PyCrypto library, offering numerous enhancements like authenticated encryption modes, Hybrid Public Key Encryption (HPKE), accelerated AES, and elliptic curve cryptography. It is actively maintained, with version 3.23.0 being the latest, and releases occur frequently. It supports Python 2.7, Python 3.7 and newer, and PyPy.

pip install pycryptodomex

Common errors

error ModuleNotFoundError: No module named 'Crypto' ↓
cause You have installed the `pycryptodomex` package, but are attempting to import modules using the `Crypto` namespace, which is reserved for the `pycryptodome` package or the legacy `PyCrypto` library. `pycryptodomex` installs its modules under the `Cryptodome` namespace to prevent conflicts.
fix
If you installed pycryptodomex, change your import statements to use Cryptodome instead of Crypto (e.g., from Cryptodome.Cipher import AES). If you intended to use the Crypto namespace, install pycryptodome instead (pip install pycryptodome).
error ModuleNotFoundError: No module named 'Cryptodome' ↓
cause You have likely installed the `pycryptodome` package, which installs its modules under the `Crypto` namespace, but your code is trying to import from `Cryptodome`. This can also occur if `pycryptodomex` was installed, but in a conflicting environment, or if there's a typo in the import statement.
fix
If you installed pycryptodome, change your import statements to use Crypto instead of Cryptodome (e.g., from Crypto.Cipher import AES). If you intended to use the Cryptodome namespace, ensure pycryptodomex is correctly installed (pip install pycryptodomex) and check for environment conflicts.
error ERROR: Command errored out with exit status 1 ↓
cause This error during `pycryptodomex` installation, particularly on Windows, usually indicates that the necessary C/C++ build tools are missing. `pycryptodomex` includes C extensions that require a compiler to build if a pre-compiled wheel is not available or compatible.
fix
Install the appropriate C++ build tools for your Python version and operating system. On Windows, this typically means installing 'Build Tools for Visual Studio' (e.g., from visualstudio.microsoft.com) and selecting the C++ development workload.
error 'utf-8' codec can't decode byte 0x81 in position X: invalid start byte ↓
cause This error often occurs when attempting to decode raw encrypted binary data (which is not plain text) directly into a string using an encoding like UTF-8. Encrypted data should be treated as bytes until decrypted, and only then decoded if it represents a text string.
fix
Ensure that encrypted data is handled as raw bytes. If you need to transmit encrypted data as a string (e.g., over HTTP), first encode the bytes using a binary-to-text encoding like Base64 (import base64; base64.b64encode(ciphertext)). On receipt, decode from Base64 back to bytes *before* attempting decryption (base64.b64decode(encoded_ciphertext)).

Warnings

breaking Support for Python 3.6 was removed in PyCryptodomeX version 3.22.0. Users on Python 3.6 must use an older version (<= 3.21.x) or upgrade their Python interpreter. ↓
fix Upgrade Python to 3.7+ or pin pycryptodomex to <3.22.0.
gotcha PyCryptodomeX imports its modules under the `Cryptodome` namespace, not `Crypto`. Attempting to import from `Crypto` (e.g., `from Crypto.Cipher import AES`) will result in a `ModuleNotFoundError` if `pycryptodome` (which uses `Crypto`) is not installed, or can lead to subtle bugs and security issues if both `pycryptodome` and `pycryptodomex` are present, as `Crypto` might resolve to the wrong package. ↓
fix Always use `from Cryptodome.<module> import <Symbol>` for `pycryptodomex` installations.
deprecated ECB (Electronic Codebook) mode for symmetric ciphers (e.g., AES) is no longer the default and is explicitly discouraged for most uses due to its lack of semantic security. Since version 3.5.0, `AES.new(key)` will raise an error, requiring the mode to be explicitly specified. ↓
fix Always explicitly specify a secure mode of operation, such as `AES.MODE_CBC`, `AES.MODE_GCM`, or `AES.MODE_EAX`, during cipher initialization (e.g., `AES.new(key, AES.MODE_CBC, iv)`). If ECB is truly intended (rarely), use `AES.new(key, AES.MODE_ECB)`.
breaking Older versions of PyCryptodome (prior to v3.19.1) had a side-channel leakage vulnerability in OAEP decryption that could be exploited to carry out a Manger attack. This was fixed in v3.19.1. ↓
fix Upgrade to PyCryptodomeX 3.19.1 or newer to mitigate this side-channel attack.
gotcha In version 3.22.0, CCM ciphers were updated to fail before encrypting or decrypting data if the data length exceeds the limit imposed by the nonce length. This prevents potential issues with integrity and confidentiality. ↓
fix Ensure that the data length used with CCM ciphers is compatible with the chosen nonce length to avoid early termination. Consult documentation for specific limits.
gotcha An infinite loop issue with RC4 for data larger than 4GB was resolved in version 3.22.0. Users processing very large data with RC4 in older versions may encounter this. ↓
fix Upgrade to PyCryptodomeX 3.22.0 or newer if using RC4 with large data, or consider using a more modern stream cipher.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.05s 26.3M
3.10 alpine (musl) - - 0.04s 26.3M
3.10 slim (glibc) wheel 1.9s 0.04s 27M
3.10 slim (glibc) - - 0.04s 27M
3.11 alpine (musl) wheel - 0.06s 29.2M
3.11 alpine (musl) - - 0.08s 29.2M
3.11 slim (glibc) wheel 2.0s 0.07s 30M
3.11 slim (glibc) - - 0.07s 30M
3.12 alpine (musl) wheel - 0.05s 20.9M
3.12 alpine (musl) - - 0.05s 20.9M
3.12 slim (glibc) wheel 1.9s 0.06s 22M
3.12 slim (glibc) - - 0.06s 22M
3.13 alpine (musl) wheel - 0.05s 20.6M
3.13 alpine (musl) - - 0.05s 20.5M
3.13 slim (glibc) wheel 1.9s 0.06s 22M
3.13 slim (glibc) - - 0.06s 22M
3.9 alpine (musl) wheel - 0.04s 25.8M
3.9 alpine (musl) - - 0.05s 25.8M
3.9 slim (glibc) wheel 2.3s 0.05s 27M
3.9 slim (glibc) - - 0.05s 27M

Imports

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates symmetric encryption and decryption using AES in CBC mode with PyCryptodomeX. It covers key and IV generation, data padding, encryption, and subsequent decryption and unpadding.

from Cryptodome.Cipher import AES
from Cryptodome.Random import get_random_bytes
from Cryptodome.Util.Padding import pad, unpad

# --- Encryption ---

# Generate a random 16-byte key for AES-128
key = get_random_bytes(16)

# Generate a random 16-byte IV for CBC mode
iv = get_random_bytes(16)

# The data to encrypt must be bytes
data_to_encrypt = b"My secret message that needs to be encrypted."

# Create an AES cipher object in CBC mode
cipher = AES.new(key, AES.MODE_CBC, iv)

# Pad the data to be a multiple of the block size (16 bytes for AES)
padded_data = pad(data_to_encrypt, AES.block_size)

# Encrypt the padded data
ciphertext = cipher.encrypt(padded_data)

print(f"Original data: {data_to_encrypt}")
print(f"Key (hex): {key.hex()}")
print(f"IV (hex): {iv.hex()}")
print(f"Ciphertext (hex): {ciphertext.hex()}")

# --- Decryption ---

# In a real scenario, key, iv, and ciphertext would be transmitted
# to the receiver. For this example, we reuse them.

# Create a new AES cipher object for decryption (same key and IV)
decipher = AES.new(key, AES.MODE_CBC, iv)

# Decrypt the ciphertext
decrypted_padded_data = decipher.decrypt(ciphertext)

# Unpad the decrypted data to get the original plaintext
decrypted_data = unpad(decrypted_padded_data, AES.block_size)

print(f"Decrypted data: {decrypted_data}")

assert decrypted_data == data_to_encrypt
print("Encryption and decryption successful!")
last verified Tue May 12
next check Fri Jun 26