{"id":690,"library":"python-jose","title":"python-jose: JOSE Implementation for Python","description":"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.","status":"active","version":"3.5.0","language":"python","source_language":"en","source_url":"https://github.com/mpdavis/python-jose/","tags":["security","JWT","JOSE","cryptography","authentication","JWS","JWE"],"install":[{"cmd":"pip install python-jose","lang":"bash","label":"Base installation (uses native Python backend)"},{"cmd":"pip install python-jose[cryptography]","lang":"bash","label":"Recommended for production (uses pyca/cryptography backend)"}],"dependencies":[{"reason":"Recommended cryptographic backend for performance and security, explicitly installed via `pip install python-jose[cryptography]`.","package":"cryptography","optional":false},{"reason":"Default native Python backend for RSA operations if no other backend is specified, generally slower.","package":"rsa","optional":true},{"reason":"Default native Python backend for ECDSA operations if no other backend is specified, generally slower.","package":"ecdsa","optional":true},{"reason":"Alternative cryptographic backend, can be installed via `pip install python-jose[pycryptodome]`.","package":"pycryptodome","optional":true}],"imports":[{"symbol":"jwt","correct":"from jose import jwt"},{"symbol":"jws","correct":"from jose import jws"},{"symbol":"jwe","correct":"from jose import jwe"},{"symbol":"jwk","correct":"from jose import jwk"}],"quickstart":{"code":"import os\nfrom jose import jwt\n\n# IMPORTANT: Use a strong, securely generated secret key in production\nSECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your-super-secret-key-please-change-me')\nALGORITHM = \"HS256\"\n\n# 1. Encode a JWT\npayload = {\"user_id\": \"123\", \"username\": \"testuser\", \"role\": \"admin\"}\nencoded_jwt = jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)\nprint(f\"Encoded JWT: {encoded_jwt}\")\n\n# 2. Decode and verify a JWT\ntry:\n    decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY, algorithms=[ALGORITHM])\n    print(f\"Decoded Payload: {decoded_payload}\")\nexcept Exception as e:\n    print(f\"Error decoding JWT: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to a supported Python version (3.9+ for python-jose 3.5.0).","message":"Python 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).","severity":"breaking","affected_versions":">=3.3.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `python-jose` version 3.4.0 or higher immediately to patch critical security vulnerabilities.","message":"Versions 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).","severity":"breaking","affected_versions":"<3.4.0"},{"fix":"Upgrade to `python-jose` 3.4.0+ to avoid `datetime.utcnow()` deprecation warnings and ensure future compatibility.","message":"The 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.","severity":"deprecated","affected_versions":"<3.4.0"},{"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.","message":"Version 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.","severity":"gotcha","affected_versions":"3.5.0"},{"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.","message":"Some 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T17:51:25.512Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"jose.exceptions.JWSError: Signature verification failed"},{"fix":"When decoding, explicitly pass the token's algorithm in the `algorithms` list: `jose.jwt.decode(token, key, algorithms=['HS256'])`.","cause":"The algorithm specified in the JWT header (`alg`) is not present in the list of algorithms explicitly allowed during the decoding process.","error":"ValueError: The token's alg header value 'HS256' does not match the provided allowed algorithms."},{"fix":"Install the necessary backend for `python-jose`: `pip install \"python-jose[cryptography]\"`.","cause":"The `cryptography` library, which provides the necessary cryptographic primitives for certain algorithms (e.g., RS256, ES256), is not installed as an optional dependency.","error":"ImportError: You must install the 'cryptography' backend to use this algorithm."},{"fix":"Install the library using pip: `pip install python-jose`.","cause":"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.","error":"ModuleNotFoundError: No module named 'jose'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"3.5.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4,"disk_size":"20.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":5,"disk_size":"37.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":4,"disk_size":"20.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":4.8,"disk_size":"36.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.09,"mem_mb":4,"disk_size":"21M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":0.22,"mem_mb":5,"disk_size":"37M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":4,"disk_size":"21M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.8,"disk_size":"36M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":4.6,"disk_size":"22.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":5.9,"disk_size":"39.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":4.6,"disk_size":"22.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":5.6,"disk_size":"38.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.15,"mem_mb":4.6,"disk_size":"23M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":0.48,"mem_mb":5.9,"disk_size":"40M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.6,"disk_size":"23M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.49,"mem_mb":5.6,"disk_size":"39M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"14.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.4,"mem_mb":5.5,"disk_size":"31.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"14.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":5.3,"disk_size":"30.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"15M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.4,"import_time_s":0.44,"mem_mb":5.5,"disk_size":"32M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"15M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":5.3,"disk_size":"31M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":4.8,"disk_size":"14.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":5.5,"disk_size":"31.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.8,"disk_size":"14.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":5.3,"disk_size":"29.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.14,"mem_mb":4.8,"disk_size":"15M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.6,"import_time_s":0.4,"mem_mb":5.5,"disk_size":"32M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.8,"disk_size":"15M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":5.3,"disk_size":"30M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":4,"disk_size":"20.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":5.1,"disk_size":"37.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":4,"disk_size":"20.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":4.9,"disk_size":"36.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.2,"import_time_s":0.12,"mem_mb":4,"disk_size":"20M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.4,"import_time_s":0.29,"mem_mb":5.1,"disk_size":"38M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":4,"disk_size":"20M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"cryptography","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":4.9,"disk_size":"37M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}