{"id":9376,"library":"types-jwt","title":"Typing stubs for PyJWT (jwt package)","description":"This library provides PEP 561 type stubs for the popular `PyJWT` library, which is commonly imported as `jwt`. It enables static type checkers like MyPy, PyCharm, and Pyright to analyze code that uses `PyJWT`. `types-jwt` is part of the `typeshed` project, which centrally manages type definitions for many third-party Python packages. `types-jwt` version 0.1.3 was released in May 2021. However, it's important to note that since `PyJWT` version 2.0.0 (released December 2020) and later include their own inline type annotations, `types-jwt` is primarily relevant for projects using older versions of `PyJWT` (pre-2.0.0) or specific legacy setups.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","jwt","pyjwt","typeshed","static-analysis"],"install":[{"cmd":"pip install types-jwt","lang":"bash","label":"Install types-jwt"}],"dependencies":[{"reason":"`types-jwt` provides type stubs for the `PyJWT` runtime library. You must install `PyJWT` (e.g., `pip install PyJWT`) to use the `jwt` module at runtime.","package":"PyJWT","optional":false},{"reason":"A static type checker like MyPy is needed to utilize the type stubs provided by `types-jwt` for static analysis.","package":"mypy","optional":true}],"imports":[{"note":"`types-jwt` is a stub-only package. You import the runtime functions from the actual `PyJWT` library (which uses the `jwt` module name).","wrong":"from types_jwt import encode","symbol":"encode","correct":"from jwt import encode"},{"note":"`types-jwt` is a stub-only package. You import the runtime functions from the actual `PyJWT` library (which uses the `jwt` module name).","wrong":"from types_jwt import decode","symbol":"decode","correct":"from jwt import decode"}],"quickstart":{"code":"import jwt\nimport os\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Dict, Any # These types are enhanced by types-jwt if PyJWT < 2.0\n\n# Note: This quickstart uses PyJWT (the runtime library)\n# types-jwt provides type hints for this code during static analysis.\n\n# Replace with a strong, secret key in a real application\nsecret_key: bytes = os.environ.get('JWT_SECRET_KEY', 'your-super-secret-key').encode('utf-8')\nalgorithm: str = \"HS256\"\n\n# 1. Encode a JWT\npayload: Dict[str, Any] = {\n    \"user_id\": 123,\n    \"username\": \"testuser\",\n    \"exp\": datetime.now(timezone.utc) + timedelta(hours=1), # Token expires in 1 hour\n    \"iat\": datetime.now(timezone.utc) # Issued at time\n}\n\ntry:\n    encoded_jwt: str = jwt.encode(payload, secret_key, algorithm=algorithm)\n    print(f\"Encoded JWT: {encoded_jwt}\")\n\n    # 2. Decode the JWT\n    decoded_payload: Dict[str, Any] = jwt.decode(\n        encoded_jwt, secret_key, algorithms=[algorithm]\n    )\n    print(f\"Decoded Payload: {decoded_payload}\")\n\nexcept jwt.ExpiredSignatureError:\n    print(\"Token has expired!\")\nexcept jwt.InvalidTokenError as e:\n    print(f\"Invalid token: {e}\")\n\n","lang":"python","description":"This quickstart demonstrates how to encode and decode a JSON Web Token using the `PyJWT` library, for which `types-jwt` provides type annotations. The example includes setting an expiration time and handling basic decoding errors. Ensure you have `PyJWT` installed for this code to run. While `types-jwt` itself is not directly imported, its presence allows type checkers to provide richer feedback on `jwt` module usage. For production, always use robust, securely generated secret keys and appropriate algorithms."},"warnings":[{"fix":"If using `PyJWT >= 2.0.0`, uninstall `types-jwt`: `pip uninstall types-jwt`. Rely on `PyJWT`'s built-in type hints.","message":"`types-jwt` (and `types-PyJWT`) are largely redundant for `PyJWT` versions 2.0.0 and higher. Starting with `PyJWT` 2.0.0 (released December 2020), the `PyJWT` library itself includes inline type annotations. Users should uninstall `types-jwt` if they are using `PyJWT >= 2.0.0` to avoid potential conflicts, redundant packages, or unexpected type-checking behavior.","severity":"breaking","affected_versions":"PyJWT >= 2.0.0"},{"fix":"Ensure both `types-jwt` (for type checking) and `PyJWT` (for runtime functionality) are installed: `pip install types-jwt PyJWT`.","message":"Installing `types-jwt` does NOT install the actual `PyJWT` runtime library. `types-jwt` only provides static type hints. To use JWT functionality (e.g., `jwt.encode`, `jwt.decode`), you must explicitly install `PyJWT` (e.g., `pip install PyJWT`) in addition to `types-jwt`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always import from `jwt` (the runtime library) and *never* from `types_jwt` in your Python code: `import jwt`.","message":"Type stub packages from `typeshed` are designed for static analysis tools (like MyPy) and should not be directly imported in your application's runtime code. All imports for JWT operations should come from the actual `PyJWT` library (i.e., `import jwt` or `from jwt import ...`). Importing from `types_jwt` will result in a `ModuleNotFoundError` or `ImportError` at runtime.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the `PyJWT` library: `pip install PyJWT`.","cause":"The `PyJWT` runtime library, which provides the `jwt` module, is not installed in your Python environment. You may have only installed `types-jwt`, which is a stub-only package.","error":"ModuleNotFoundError: No module named 'jwt'"},{"fix":"Uninstall `types-jwt` if you are using `PyJWT` version 2.0.0 or newer: `pip uninstall types-jwt`. Rely on the inline types from `PyJWT`.","cause":"There is a conflict or redundancy between the inline type annotations provided by `PyJWT` version 2.0.0+ and the external stubs from `types-jwt`. `PyJWT` itself began including type information in version 2.0.0.","error":"MyPy error: Incompatible types in assignment (expression has type \"bytes\", variable has type \"str\") or similar type errors related to `jwt.encode()` or `jwt.decode()` when both `PyJWT >= 2.0.0` and `types-jwt` are installed."},{"fix":"Ensure `PyJWT` is installed (`pip install PyJWT`). Verify your environment setup. If using `PyJWT < 2.0.0`, ensure `types-jwt` is installed. If using `PyJWT >= 2.0.0`, ensure `types-jwt` is *not* installed and that `PyJWT`'s own `py.typed` file is being recognized.","cause":"This often occurs if `PyJWT` is not installed, or if there's an environment issue where MyPy cannot find the correct `PyJWT` installation to apply the stubs to. Also, older `PyJWT` versions might have inconsistent typing.","error":"MyPy error: 'Module' object has no attribute 'encode' or 'decode' even after installing types-jwt."}]}