Install & Compatibility
Where this runs
tested against v3.23.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.050s · 26.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.054s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AES
✓ from Crypto.Cipher import AES
✗ from Cryptodome.Cipher import AES
The `pycryptodome` package installs its modules under the `Crypto` namespace for backward compatibility with the old `PyCrypto` library. Avoid `Cryptodome` unless `pycryptodomex` is explicitly installed.
get_random_bytes
✓ from Crypto.Random import get_random_bytes
Standard import path for cryptographic random number generation.
PBKDF2
✓ from Crypto.Protocol.KDF import PBKDF2
Standard import path for Password-Based Key Derivation Function 2.
RSA
✓ from Crypto.PublicKey import RSA
Standard import path for RSA public key operations.
This quickstart demonstrates symmetric encryption and decryption using AES in GCM (Galois/Counter Mode), an authenticated encryption mode. It shows how to derive a key from a password using PBKDF2, generate a random salt and nonce, encrypt data, and then decrypt and verify its integrity.
from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
from Crypto.Protocol.KDF import PBKDF2
import os
# Simulate a password for key derivation
password = os.environ.get('CRYPTO_PASSWORD', 'mysecretpassword').encode('utf-8')
# Generate a random salt
salt = get_random_bytes(16)
# Derive a strong key from the password and salt
# Use default iterations (or a high number like 1000000)
key = PBKDF2(password, salt, dkLen=32) # 32 bytes for AES-256
# The data to encrypt
data = b"This is a super secret message."
# Encrypt with AES GCM
# A nonce is automatically generated by AES.new() in GCM mode
cipher = AES.new(key, AES.MODE_GCM)
ciphertext, tag = cipher.encrypt_and_digest(data)
nonce = cipher.nonce
print(f"Original: {data}")
print(f"Salt: {salt.hex()}")
print(f"Nonce: {nonce.hex()}")
print(f"Ciphertext: {ciphertext.hex()}")
print(f"Tag: {tag.hex()}")
# --- Decryption ---
# Re-derive the key using the same password and salt
decryption_key = PBKDF2(password, salt, dkLen=32)
# Create a new cipher object for decryption using the received key and nonce
decrypt_cipher = AES.new(decryption_key, AES.MODE_GCM, nonce=nonce)
# Decrypt and verify
try:
plaintext = decrypt_cipher.decrypt_and_verify(ciphertext, tag)
print(f"Decrypted: {plaintext}")
except ValueError:
print("Decryption failed or message was tampered with!")
Debug
Known issues
breakingPyCryptodome uses the `Crypto` top-level package name. Installing `pycryptodome` in an environment that also has the unmaintained `PyCrypto` library will cause import conflicts and unexpected behavior. Always use virtual environments and ensure only one is installed.fixAlways install `pycryptodome` in a dedicated virtual environment. If a project requires coexistence with `PyCrypto`, install `pycryptodomex` instead, which uses the `Cryptodome` namespace.
affects: All versions
breakingPython 3.6 support was removed in version 3.22.0. Users on Python 3.6 will need to pin to an older version of PyCryptodome (e.g., <3.22.0).fixUpgrade to Python 3.7 or newer, or pin `pycryptodome` to a version older than 3.22.0 (e.g., `pycryptodome<3.22.0`).
affects: >=3.22.0
breakingECB mode is no longer the default for symmetric ciphers. Calling `AES.new(key)` will now fail. ECB is not semantically secure and should generally be avoided.fixExplicitly specify the desired mode, e.g., `AES.new(key, AES.MODE_GCM)` or `AES.new(key, AES.MODE_CBC)`. If ECB is intentionally needed, use `AES.new(key, AES.MODE_ECB)`.
affects: All versions, compared to PyCrypto
breakingSeveral methods like `sign()`, `verify()`, `encrypt()`, `decrypt()`, `blind()`, `unblind()` were removed from public key objects (RSA, DSA, ElGamal) due to security concerns or maintenance difficulties.fixUse dedicated modules for public-key operations: `Crypto.Cipher.PKCS1_OAEP` for RSA encryption/decryption, `Crypto.Signature.pkcs1_15` or `Crypto.Signature.pss` for RSA signing, and `Crypto.Signature.DSS` for DSA signing.
affects: All versions, compared to PyCrypto
gotchaA side-channel leakage vulnerability (Manger attack) in OAEP decryption was fixed.fixUpgrade to version 3.19.1 or newer to mitigate potential side-channel attacks on OAEP decryption.
affects: <3.19.1
gotchaAn infinite loop bug affecting RC4 ciphers when processing data larger than 4GB was resolved.fixUpgrade to version 3.22.0 or newer if using RC4 with potentially large datasets. Consider migrating away from RC4 as it is generally considered insecure for modern applications.
affects: <3.22.0
gotchaFor HashEdDSA and Ed448, the `sign()` and `verify()` methods incorrectly modified the state of the XOF (eXtendable Output Function).fixUpgrade to version 3.23.0 or newer to ensure correct state management for HashEdDSA and Ed448 operations.
affects: <3.23.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'Crypto'
This error typically occurs when the `pycryptodome` library is not installed, or there is a conflict with the older `pycrypto` library, or due to case sensitivity issues on Windows where `crypto` might be installed instead of `Crypto` in the site-packages.
fixFirst, uninstall any existing `pycrypto` or `crypto` packages: `pip uninstall pycrypto crypto`. Then, install `pycryptodome`: `pip install pycryptodome`. Ensure your imports use `from Crypto.Cipher import AES` (or similar) as intended by `pycryptodome`.
TypeError: argument 2 must be bytes, not bytearray
This error, often seen with `strxor`, arises when both the old `pycrypto` and `pycryptodome` packages are installed concurrently, causing module interference.
fixUninstall the older `pycrypto` package: `pip uninstall pycrypto`.
ERROR: Failed building wheel for pycryptodome
This installation error usually indicates missing system-level build tools (like C compilers), missing Python development headers, or an incompatible Python version on your system.
fixEnsure you have necessary build tools installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows). Also, ensure your Python development headers are installed (e.g., `python3-dev` on Debian/Ubuntu). It's also recommended to upgrade pip: `pip install --upgrade pip`.
ValueError: Ciphertext with incorrect length
This error during decryption typically means the provided ciphertext length does not match the expected block size or padding scheme, often due to corrupted data, incorrect key usage, or improper padding removal settings.
fixVerify that the ciphertext has not been altered, the correct key is being used, and the padding scheme (e.g., PKCS7, none) and mode of operation (e.g., CBC, GCM) specified during decryption precisely match those used during encryption.
Upgrade
Version history
3.23.0latest on PyPI · released May 17, 2025
Audit
Dependencies
gmpoptionalOptional for faster public key operations on Unix-like systems, if compiled from source.
Visual Studio Build ToolsoptionalRequired for compiling C extensions from source on Windows if wheels are not available or custom compilation is desired.