Install & Compatibility
Where this runs
tested against v3.5.0.20260408 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 38MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.2s · import 0.000s · 38MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jwt
✓ from jose_stubs import jwt
✗ from jose-stubs import jwt
This quickstart demonstrates basic JWT (JSON Web Token) encoding and decoding using the `python-jose` library. Installing `types-python-jose` alongside it provides static type checking benefits for these operations. It shows how to encode a payload into a JWT using a symmetric key and then decode it. Remember to manage your `SECRET_KEY` securely in a production environment, ensuring it meets the length requirements for your chosen algorithm (e.g., at least 32 bytes for HS256). The `python-jose` library supports various JOSE specifications including JWS, JWE, and JWK, with different cryptographic backends.
import os
from jose import jwt
from jose.constants import ALGORITHMS
# In a real application, load a secret from environment variables
# or a secure configuration management system.
SECRET_KEY = os.environ.get('JOSE_SECRET_KEY', 'your-secret-key-that-is-at-least-32-bytes-long')
# Encoding a JWT
payload = {
"sub": "user123",
"name": "John Doe",
"admin": True
}
# Use a strong algorithm like HS256 for symmetric keys
# For asymmetric keys (RS256, ES256), you'd use public/private key pairs.
algorithm = ALGORITHMS.HS256
# Ensure your secret is bytes for HS algorithms
if isinstance(SECRET_KEY, str):
# Pad secret if too short for HS256 (requires 32 bytes for 256-bit key)
SECRET_KEY_BYTES = SECRET_KEY.encode('utf-8').ljust(32, b'\0')[:32]
else:
SECRET_KEY_BYTES = SECRET_KEY
encoded_jwt = jwt.encode(payload, SECRET_KEY_BYTES, algorithm=algorithm)
print(f"Encoded JWT: {encoded_jwt}")
# Decoding a JWT
try:
decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY_BYTES, algorithms=[algorithm])
print(f"Decoded payload: {decoded_payload}")
except jwt.JWTError as e:
print(f"JWT decoding error: {e}")
# Example with an incorrect key (for demonstration of type safety and error handling)
try:
wrong_key = b"wrong-secret".ljust(32, b'\0')[:32] # Pad for demonstration
jwt.decode(encoded_jwt, wrong_key, algorithms=[algorithm])
except jwt.JWTError as e:
print(f"Expected error with wrong key: {e}")
Debug
Known issues
gotchaAttempting to import or run code directly from `types-python-jose` will result in `ImportError` or `AttributeError`.fixAlways import functionality from the actual `python-jose` runtime library (e.g., `from jose import jwt`). `types-python-jose` only provides `.pyi` stub files for type checkers and is not meant for runtime execution.
affects: All versions
gotchaThis stub package requires the `python-jose` runtime library to be installed and present for your application to actually function.fixEnsure `pip install python-jose` is run in your environment. For specific cryptographic backends, consider `pip install python-jose[cryptography]` (recommended) or `python-jose[pycryptodome]` to include necessary cryptographic dependencies.
affects: All versions
deprecatedThe `python-jose` library itself has been noted as 'barely maintained' by some sources as of early 2024, suggesting `PyJWT` or `joserfc` as potentially more secure and actively maintained alternatives for JWT operations.fixEvaluate `python-jose`'s current maintenance status and consider migrating to `PyJWT` or `joserfc` if active development and security patches are critical for your application. If migrating, ensure to update your imports and API calls accordingly.
affects: python-jose versions < 3.5.0 and potentially current/future versions if maintenance doesn't improve.
breakingWhile typeshed aims for minimal breaking changes, any version bump of `types-python-jose` can introduce changes that might cause your code to fail type checking, especially if the underlying `python-jose` library or typing standards evolve.fixPin the version of `types-python-jose` to a known compatible version (e.g., `types-python-jose==3.5.0.20260408`) and test thoroughly before updating. Alternatively, use the same version bounds for `types-python-jose` as for `python-jose` (e.g., `types-python-jose~=3.5`).
affects: All versions, particularly when updating `types-python-jose` across major/minor versions or when `python-jose` itself updates significantly.
Upgrade
Version history
3.5.0.20260408latest on PyPI · released Apr 8, 2026
Audit
Dependencies
python-joserequiredProvides the runtime functionality for which these are stubs. This stub package aims to provide accurate annotations for `python-jose==3.5.*`.