Install & Compatibility
Where this runs
tested against v1.9.3 · 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.249s · 43.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.232s · 45MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Key
✓ from pyseto import Key
✗ import Key
Key is a class within the pyseto package and needs to be imported explicitly.
This quickstart demonstrates how to create and verify a PASETO token using the v4.public protocol for asymmetric signatures. It covers key generation from PEM bytes, encoding a payload with a footer, and decoding/verifying the token. It uses the built-in `json_serializer`/`json_deserializer` for dictionary payloads.
import os
import pyseto
from pyseto import Key
# --- Example for v4.public (Asymmetric Signature) ---
# In a real application, keys should be loaded securely, e.g., from environment variables or a KMS.
# For demonstration, we use hardcoded keys. DO NOT USE IN PRODUCTION AS IS.
# These PEMs are for Ed25519 (v4.public)
private_key_pem = os.environ.get(
'PSETO_V4_PRIVATE_KEY_PEM',
b"""-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEILTL+0PfTOIQcn2VPkpxMwf6Gbt9n4UEFDjZ4RuUKjd0
-----END PRIVATE KEY-----
""").encode('utf-8')
public_key_pem = os.environ.get(
'PSETO_V4_PUBLIC_KEY_PEM',
b"""-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAHrnbu7wEfAP9cGBOAHHwmH4Wsot1ciXBHwBBXQ4gsaI=
-----END PUBLIC KEY-----
""").encode('utf-8')
# 1. Create a private key for signing
private_key = Key.new(version=4, purpose="public", key=private_key_pem)
# 2. Encode/Sign a PASETO token
payload = {"data": "this is a signed message", "user_id": "123"}
footer = {"kid": "v4-public-key-001"}
token = pyseto.encode(private_key, payload, footer=footer, serializer=pyseto.json_serializer)
print(f"Generated Token: {token.decode()}")
# 3. Create a public key for verification
public_key = Key.new(version=4, purpose="public", key=public_key_pem)
# 4. Decode and verify the token
decoded_token = pyseto.decode(public_key, token, deserializer=pyseto.json_deserializer)
# The payload and footer are accessible as dictionary-like objects if deserializer is used
print(f"Decoded Payload: {decoded_token.payload}")
print(f"Decoded Footer: {decoded_token.footer}")
assert decoded_token.payload['data'] == "this is a signed message"
assert decoded_token.footer['kid'] == "v4-public-key-001"
print("Token verified successfully!")
Debug
Known issues
breakingEarlier versions of PySETO (e.g., <1.8.0) used strict version pinning for core dependencies like `cryptography` and `pycryptodomex`. This could lead to `ResolutionImpossible` errors during installation when combined with other libraries that had different `cryptography` requirements (e.g., `pyopenssl`).fixUpgrade PySETO to the latest version (1.8.0+ recommended) where dependency ranges are generally more flexible. If conflicts persist, try isolating dependency environments or manually resolving conflicts by specifying compatible versions of the conflicting libraries.
affects: <1.8.0 (potentially up to 1.7.5)
deprecatedPASETO v2 is expected to be deprecated in the PASETO standard due to underlying cryptographic primitives. While PySETO supports v2, new development should ideally target PASETO versions 3 or 4 for future compatibility and enhanced security.fixMigrate new token implementations to PASETO v3 or v4, which utilize modern and robust cryptographic algorithms like XChaCha20 and EdDSA.
affects: All versions supporting PASETO v2
gotchaThe top-level `pyseto.encode()` and `pyseto.decode()` functions are aliases to `encode()` and `decode()` methods of a global `Paseto` class instance created with default settings. If you intend to use custom `Paseto` instance settings (e.g., different default expiration times or `iat` inclusion), you must instantiate `Paseto` directly and call its methods, rather than relying on `pyseto.encode/decode`.fixIf custom `Paseto` behavior is required, explicitly create a `Paseto` instance: `my_paseto = Paseto(default_exp=3600)` and then use `my_paseto.encode()` and `my_paseto.decode()`.
affects: All versions
Errors
Common errors & fixes
ERROR: Cannot install pyopenssl==X.Y.Z and pyseto==A.B.C because these package versions have conflicting dependencies.
Conflicting strict version requirements for a shared dependency (e.g., `cryptography` or `pycryptodomex`) between `pyseto` and another installed library (like `pyopenssl`).
fixTry updating `pyseto` to the latest version. If the error persists, attempt to install specific versions of `pyopenssl` and `pyseto` that have compatible `cryptography` or `pycryptodomex` requirements. Consult the `setup.py` or `pyproject.toml` of both packages for their exact dependency specifications. Using a dedicated virtual environment for each project can prevent such conflicts.
NameError: name 'Key' is not defined
The `Key` class, used for creating PASETO keys, was not imported explicitly from the `pyseto` package.
fixAdd `from pyseto import Key` at the top of your Python file where `Key` is used.
pyseto.exceptions.DecryptError: Failed to decrypt the message
This error occurs during `pyseto.decode()` when attempting to decrypt a `local` PASETO token if the provided symmetric key is incorrect, or if the token has been tampered with.
fixEnsure the correct symmetric key is used for decryption. Verify that the token itself has not been altered or corrupted. For `public` tokens, a `VerifyError` would typically indicate a signature mismatch.
pyseto.exceptions.VerifyError: Failed to verify the message
This error occurs during `pyseto.decode()` when attempting to verify a `public` PASETO token if the provided public key does not match the private key used for signing, or if the token's signature has been tampered with.
fixEnsure the correct public key (corresponding to the private key used for signing) is provided for verification. Validate the integrity of the token and ensure it has not been modified after creation.
Upgrade
Version history
1.9.3latest on PyPI · released May 14, 2026
Audit
Dependencies
cryptographyrequiredCore cryptographic operations.
pycryptodomexrequiredAlternative cryptographic backend, often for performance or specific algorithms.