PyNaCl: Python binding to the Networking and Cryptography (NaCl) library

1.6.2 verified Tue May 12 auth: no python install: stale quickstart: stale

PyNaCl is a Python binding to the Networking and Cryptography (NaCl) library, providing cryptographic operations such as digital signatures, secret-key and public-key encryption, hashing, and password-based key derivation. The current version is 1.6.2, released on January 1, 2026. PyNaCl follows a regular release cadence, with updates approximately every 1-2 years.

pip install pynacl

Common errors

error ERROR: The 'make' utility is missing from PATH ↓

cause PyNaCl often requires compilation of its C dependencies (libsodium) during installation if a pre-built wheel is not available for your system. This error indicates that the 'make' build tool, or other necessary C/C++ compilers, are not installed or not found in your system's PATH.

fix

On Linux, install build-essential (Debian/Ubuntu) or Development Tools (CentOS/Fedora). On Windows, ensure you have an up-to-date pip (use python -m pip install -U pip) to leverage pre-built wheels, or install Microsoft Visual C++ Build Tools. If wheels are still an issue, manually install libsodium development libraries for your OS and set SODIUM_INSTALL=system before pip install pynacl.

error ModuleNotFoundError: No module named 'nacl' ↓

cause This error occurs when the `pynacl` package, which is imported as `nacl` in Python code, is either not installed, installed in a different Python environment than the one being used, or its C components (`_sodium`) failed to load correctly during installation.

fix

Ensure pynacl is installed in the active Python environment using pip install pynacl. If already installed, check for Python version mismatches (e.g., if you have multiple Python installations and pip points to a different one). If running in a virtual environment, ensure it's activated. Sometimes reinstalling after upgrading pip (python -m pip install -U pip && pip install pynacl) can resolve this.

error RuntimeError: PyNaCl library needed in order to use voice ↓

cause This specific error commonly arises when `pynacl` is a required dependency for another library (e.g., `discord.py` for voice functionalities), but `pynacl` itself is not correctly installed or cannot be found by the dependent library at runtime.

fix

Explicitly install pynacl using pip install pynacl. If you are using discord.py or a similar library, you might need to install it with its voice capabilities: pip install discord.py[voice] which typically ensures pynacl is included. Verify that pynacl is installed in the correct Python environment.

Warnings

breaking PyNaCl 1.6.2 requires Python 3.8 or higher. ↓

fix Upgrade your Python installation to version 3.8 or higher.

gotcha Ensure that the 'libsodium' library is installed on your system, as PyNaCl depends on it for cryptographic operations. ↓

fix Install the 'libsodium' library using your system's package manager or by following the installation instructions provided in the PyNaCl documentation.

breaking The class `PublicKeyBox` has been removed from the `nacl.public` module in PyNaCl versions 1.5.0 and later. This will result in an `ImportError`. ↓

fix Replace `PublicKeyBox` with `Box` in your code. The `Box` class provides equivalent functionality for public-key authenticated encryption. Consult the PyNaCl documentation for guidance on migrating from `PublicKeyBox` to `Box`.

breaking The 'PublicKeyBox' class was removed from 'nacl.public' in PyNaCl version 1.6.0. If you are using PyNaCl 1.6.0 or later, use 'Box' instead. ↓

fix Update your code to import 'Box' from 'nacl.public' instead of 'PublicKeyBox'.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

PublicKeyBox
```
from nacl.public import PublicKeyBox
```
Ensure correct import path to access PublicKeyBox class.
SecretBox
```
from nacl.secret import SecretBox
```
Ensure correct import path to access SecretBox class.
SigningKey
```
from nacl.signing import SigningKey
```
Ensure correct import path to access SigningKey class.
VerifyKey
```
from nacl.signing import VerifyKey
```
Ensure correct import path to access VerifyKey class.

Quickstart stale last tested: 2026-04-23

This example demonstrates how to generate a private key, derive the corresponding public key, create a PublicKeyBox for encryption, and encrypt and decrypt a message using PyNaCl.

from nacl.public import PrivateKey, PublicKey, PublicKeyBox

# Generate a private key
private_key = PrivateKey.generate()

# Derive the corresponding public key
public_key = private_key.public_key

# Create a PublicKeyBox for encryption
box = PublicKeyBox(public_key)

# Encrypt a message
message = b"Secret message"
encrypted = box.encrypt(message)

# Decrypt the message
decrypted = box.decrypt(encrypted)
print(decrypted.decode())