python-jose

library3.5.0pypypi✓ verified 28d ago

python-jose is an active Python library implementing the JSON Object Signing and Encryption (JOSE) standards, including JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), JSON Web Algorithms (JWA), and JSON Web Tokens (JWT). Currently at version 3.5.0, it maintains a regular release schedule with significant updates to Python version support and cryptographic backends.

auth-security serialization

pip install python-jose

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYTHON-JOSE

python-jose

auth-securitypythonv3.5.0

Install

2.4s avg

Import

266ms

Disk

36MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.5.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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.269s · 37.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.4s · import 0.263s · 38MB

36MB installed

● package 36MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jwt

✓ from jose import jwt

jws

✓ from jose import jws

jwe

✓ from jose import jwe

jwk

✓ from jose import jwk

This quickstart demonstrates encoding and decoding a JSON Web Token (JWT) using a symmetric (HS256) algorithm. For asymmetric algorithms (like RS256), you would use public/private key pairs instead of a shared secret. Ensure `JWT_SECRET_KEY` is set securely in your environment for production use.

import os from jose import jwt # IMPORTANT: Use a strong, securely generated secret key in production SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your-super-secret-key-please-change-me') ALGORITHM = "HS256" # 1. Encode a JWT payload = {"user_id": "123", "username": "testuser", "role": "admin"} encoded_jwt = jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM) print(f"Encoded JWT: {encoded_jwt}") # 2. Decode and verify a JWT try: decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY, algorithms=[ALGORITHM]) print(f"Decoded Payload: {decoded_payload}") except Exception as e: print(f"Error decoding JWT: {e}")

Debug

Known issues

breakingPython 3.8 support was removed in version 3.5.0. Prior versions also removed support for Python 3.6/3.7 (v3.4.0) and 2.7/3.5 (v3.3.0).

fix

Upgrade to a supported Python version (3.9+ for python-jose 3.5.0).

affects: >=3.3.0

gotchaThe default cryptographic backend for `python-jose` has changed across versions (PyCryptodome in 2.0.0, native Python `rsa` in 3.0.0). Since 3.3.0, while native backends (rsa/ecdsa) are always installed, `pyca/cryptography` is the recommended backend for performance and security. Not installing with `pip install python-jose[cryptography]` can lead to slower native Python implementations being used by default.

fix

Always install with `pip install python-jose[cryptography]` for production environments to ensure optimal performance and security. Review your installed dependencies to confirm `cryptography` is active.

affects: All versions

breakingVersions prior to 3.4.0 were vulnerable to Improper Handling of Highly Compressed Data (CVE-2024-33664, JWE size limit) and Improper Verification of Cryptographic Signature (CVE-2024-33663, signing JWT with public key forbidden).

fix

Upgrade to `python-jose` version 3.4.0 or higher immediately to patch critical security vulnerabilities.

affects: <3.4.0

deprecatedThe usage of `datetime.utcnow()` was replaced with `datetime.now(UTC)` in version 3.4.0 due to `utcnow()` being deprecated in Python 3.11. Code relying on `utcnow()` with older versions might encounter deprecation warnings.

fix

Upgrade to `python-jose` 3.4.0+ to avoid `datetime.utcnow()` deprecation warnings and ensure future compatibility.

affects: <3.4.0

gotchaVersion 3.5.0 removed `get_random_bytes` from the `cryptography` backend and removed sensitive information from `JWKError` exceptions. If your code directly accessed `get_random_bytes` through the backend or relied on specific error message content from `JWKError`, this might be a breaking change.

fix

Review code for direct access to backend-specific utilities like `get_random_bytes` or reliance on `JWKError` message specifics. Adapt to the new behavior or use standard `os.urandom` if random bytes are needed.

affects: 3.5.0

gotchaSome external resources suggest `python-jose` might be less actively maintained compared to alternatives like `PyJWT` or `joserfc` and recommend considering these for new projects or migrations. While `python-jose` still receives updates, this feedback indicates a potential concern for long-term support or advanced features.

fix

Evaluate your project's specific needs for JOSE implementation. If long-term maintenance, broader community support, or specific advanced features are critical, consider alternatives like `PyJWT` or `joserfc` (from Authlib), which may offer different API structures.

affects: All versions

Errors

Common errors & fixes

jose.exceptions.JWSError: Signature verification failed

The token's signature does not match the signature generated using the provided key and algorithm, indicating tampering, an incorrect key, or an invalid token.

fix

Ensure the correct secret key (or public key for asymmetric algorithms) is provided to `jose.jwt.decode`, and that the token is valid and untampered.

ValueError: The token's alg header value 'HS256' does not match the provided allowed algorithms.

The algorithm specified in the JWT header (`alg`) is not present in the list of algorithms explicitly allowed during the decoding process.

fix

When decoding, explicitly pass the token's algorithm in the `algorithms` list: `jose.jwt.decode(token, key, algorithms=['HS256'])`.

ImportError: You must install the 'cryptography' backend to use this algorithm.

The `cryptography` library, which provides the necessary cryptographic primitives for certain algorithms (e.g., RS256, ES256), is not installed as an optional dependency.

fix

Install the necessary backend for `python-jose`: `pip install "python-jose[cryptography]"`.

ModuleNotFoundError: No module named 'jose'

The `python-jose` library has not been installed, or the Python environment where the code is executed does not have access to the installed library.

fix

Install the library using pip: `pip install python-jose`.

Upgrade

Version history

3.5.0latest on PyPI · released May 28, 2025

Audit

Dependencies

cryptographyrequiredRecommended cryptographic backend for performance and security, explicitly installed via `pip install python-jose[cryptography]`.

rsaoptionalDefault native Python backend for RSA operations if no other backend is specified, generally slower.

ecdsaoptionalDefault native Python backend for ECDSA operations if no other backend is specified, generally slower.

pycryptodomeoptionalAlternative cryptographic backend, can be installed via `pip install python-jose[pycryptodome]`.

Agent activity

70 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mpdavis/python-jose ↗

packagehttps://pypi.org/project/python-jose/ ↗

docshttps://python-jose.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/mpdavis/python-jose/blob/master/CHANGELOG.md ↗