Python JWT

4.1.0 · active · verified Tue Apr 14

python-jwt is a Python module for generating and verifying JSON Web Tokens (JWTs). It leverages the `cryptography` library for cryptographic operations and provides a straightforward API for encoding and decoding tokens. The current version is 4.1.0, with an intermittent, feature-driven release cadence.

Warnings

breaking Version 4.0.0 introduced a hard dependency on `cryptography` version 3.x.x or higher. If you were using an older version of `cryptography`, upgrading `python-jwt` to 4.x will likely require upgrading `cryptography` as well.
Fix: Ensure your `cryptography` dependency is updated to `cryptography>=3.0.0`. If using `pip`, `pip install --upgrade python-jwt cryptography` should resolve it.
gotcha The `jwt.decode()` function requires an `algorithms` parameter, which must be a list of allowed algorithms (e.g., `['HS256']`). Passing a single string (e.g., `algorithm='HS256'`) will result in a `TypeError`.
Fix: Always pass `algorithms` as a list: `jwt.decode(token, key, algorithms=['HS256'])`.
gotcha JWT validation, especially for expiry (`exp`), not-before (`nbf`), audience (`aud`), and issuer (`iss`) claims, is crucial. While `python-jwt` handles these by default if present in the payload and `verify_claims=True` (default), you must handle `ExpiredSignatureError` and `InvalidTokenError` during decoding.
Fix: Wrap your `jwt.decode()` calls in `try...except jwt.exceptions.ExpiredSignatureError` and `try...except jwt.exceptions.InvalidTokenError` blocks to gracefully handle invalid or expired tokens.

Install

pip install python-jwt Install latest version

Imports

encode
```
from jwt import encode
```
decode
```
from jwt import decode
```
jwt
```
import jwt
```
The common practice is to import directly from `jwt` after installation, not `python_jwt`.

Quickstart

This example demonstrates how to encode a JWT with a payload and secret key, and then decode it, including basic error handling for common JWT exceptions. Remember to use a strong, securely stored secret key in production.

import jwt
import datetime

# Your secret key for signing the token
secret_key = "your-super-secret-key-that-should-be-kept-safe"

# Define the token payload with an expiry time
payload = {
    'user_id': 123,
    'username': 'testuser',
    'exp': datetime.datetime.utcnow() + datetime.timedelta(minutes=30),
    'iat': datetime.datetime.utcnow()
}

# Encode the token using HS256 algorithm
token = jwt.encode(payload, secret_key, algorithm='HS256')
print(f"Encoded Token: {token}")

# Decode the token, specifying the expected algorithm
try:
    decoded_payload = jwt.decode(token, secret_key, algorithms=['HS256'])
    print(f"Decoded Payload: {decoded_payload}")
except jwt.exceptions.ExpiredSignatureError:
    print("Error: Token has expired!")
except jwt.exceptions.InvalidTokenError as e:
    print(f"Error: Invalid Token - {e}")

view raw JSON →