PyJWT

Warnings

• breaking jwt.encode() returns str in 2.x, not bytes. Calling .decode('utf-8') on the result raises AttributeError.
  Fix: Remove any .decode('utf-8') calls on the encode() return value. It is already a str in 2.0+.
• breaking Exception aliases ExpiredSignature, InvalidAudience, and InvalidIssuer were removed in 2.0. Code catching these names will silently fail to catch the exception.
  Fix: Catch jwt.ExpiredSignatureError, jwt.InvalidAudienceError, and jwt.InvalidIssuerError respectively.
• breaking jwt.decode(token, key, verify=False) does nothing in 2.x and raises a deprecation warning. Passing extra kwargs to decode() is flagged RemovedInPyjwt3Warning.
  Fix: Use options={"verify_signature": False} to skip verification, e.g. jwt.decode(token, options={"verify_signature": False}).
• breaking CVE-2026-32597 (GHSA-752w-5fwx-jx9f, CVSS 7.5 HIGH): versions < 2.12.0 silently accept JWS tokens with unknown crit header extensions, violating RFC 7515 §4.1.11.
  Fix: Upgrade to pyjwt>=2.12.0 immediately.
• gotcha algorithms= parameter is required in jwt.decode(). Omitting it accepts any algorithm, enabling alg:none and key-confusion attacks (CVE-2022-29217).
  Fix: Always pass a hard-coded allowlist: jwt.decode(token, key, algorithms=["HS256"]). Never derive the list from the token header.
• gotcha Optional claims (exp, iat, nbf, sub, jti) are only validated when present. A token missing exp is accepted even if you call decode() without options.
  Fix: Pass options={"require": ["exp", "iat", "sub"]} to enforce presence and validation of critical claims.
• gotcha RSA/EC/PS*/EdDSA algorithms silently fail with an unhelpful ImportError or InvalidAlgorithmError if the cryptography package is not installed.
  Fix: Install pyjwt[cryptography] when using any non-HMAC algorithm.

Install

• pip install pyjwt HMAC-only (HS256/384/512)
• pip install pyjwt[cryptography] With asymmetric algorithm support (RS*, ES*, PS*, EdDSA)

Imports

• jwt (module)

  import jwt

  Top-level module exposes encode(), decode(), get_unverified_header(), and all exception classes.
• PyJWKClient

  from jwt import PyJWKClient

  Used for automatic JWKS endpoint fetching and key resolution (e.g. Auth0, Cognito).
• PyJWK

  from jwt import PyJWK

  Wraps a single JSON Web Key; returned by PyJWKClient.get_signing_key_from_jwt().
• ExpiredSignatureError

  from jwt.exceptions import ExpiredSignatureError

  ExpiredSignature (no 'Error' suffix) was removed in 2.0. Use ExpiredSignatureError, InvalidAudienceError, InvalidIssuerError.
• InvalidAudienceError

  from jwt.exceptions import InvalidAudienceError

  InvalidAudience (no 'Error' suffix) was removed in 2.0.
• PyJWKClientConnectionError

  from jwt import PyJWKClientConnectionError

  Raised when PyJWKClient cannot reach the JWKS endpoint; exported at top level since 2.8.0.

Quickstart

Encode and decode a signed JWT with HS256, validating exp/aud/iss claims. token is a str in PyJWT 2.x.

import os
import jwt
from datetime import datetime, timezone, timedelta

SECRET = os.environ.get('JWT_SECRET', 'change-me-use-32-plus-chars-prod!')

# Encode
payload = {
    "sub": "user-123",
    "iss": "my-service",
    "aud": "my-api",
    "exp": datetime.now(tz=timezone.utc) + timedelta(hours=1),
    "iat": datetime.now(tz=timezone.utc),
}
token: str = jwt.encode(payload, SECRET, algorithm="HS256")
print("token type:", type(token))  # <class 'str'> in 2.x

# Decode — always pass algorithms= to prevent alg confusion attacks
try:
    decoded = jwt.decode(
        token,
        SECRET,
        algorithms=["HS256"],       # required; never omit
        audience="my-api",          # validates 'aud' claim
        issuer="my-service",        # validates 'iss' claim
        options={"require": ["exp", "iat", "sub"]},
    )
    print(decoded)
except jwt.ExpiredSignatureError:
    print("token expired")
except jwt.InvalidTokenError as e:
    print("invalid token:", e)