PyJWT 安装指南:pip 安装与 cryptography 加密依赖(pyjwt[crypto])详解
PyJWT 安装指南:pip 安装与 cryptography 加密依赖(pyjwt[crypto])详解
PyJWT(项目包名为 pyjwt)是 Python 中实现 JSON Web Token(RFC 7519)编码与解码的库,几乎所有应用的第一步都是正确地把它装进环境。本篇以 docs/installation.rst 为核心骨架,结合仓库内的 pyproject.toml、jwt/algorithms.py、jwt/api_jws.py 与 tox.ini 源码证据,系统讲解基础安装、可选加密依赖的安装时机与推荐写法,并给出安装后的验证方法。读完你将掌握 PyJWT 在不同签名算法场景下的正确安装姿势,并能判断“装好了但没有 cryptography”这类常见误区的真实影响。
一、基础安装:一行 pip 命令即可
PyJWT 已发布到 PyPI,最简单的方式是通过 pip 安装:
$ pip install pyjwt
仓库 pyproject.toml 中记录了该包的元数据:项目名称为 PyJWT(PyPI 包名与导入名均不区分大小写,因此 pip install pyjwt 与 pip install PyJWT 等价,README.rst 中也使用了 pip install PyJWT 的写法),核心运行时依赖极少——仅对 Python 3.11 以下版本额外要求 typing_extensions >= 4.0(见 pyproject.toml)。
安装完成后即可导入并立刻使用不依赖任何第三方加密库的 HMAC 算法:
>>> import jwt
>>> encoded = jwt.encode({"some": "payload"}, "secret", algorithm="HS256")
>>> jwt.decode(encoded, "secret", algorithms=["HS256"])
{'some': 'payload'}
注意:PyJWT 2.x 支持 Python 3.9 及以上版本(
requires-python = ">=3.9",见 pyproject.toml)。如果你的环境是更早的 Python 版本,需要确认 pip 解析到的 PyJWT 版本与解释器兼容。
二、可选加密依赖:什么时候需要 cryptography?
pip install pyjwt 安装的是纯 Python 核心,只包含 HMAC 对称签名(HS256/HS384/HS512)所需的实现。PyJWT 将 RSA、ECDSA、EdDSA 等非对称数字签名算法的底层密码学操作委托给 cryptography 库,因此这些算法属于可选依赖。
官方文档(docs/installation.rst)的表述是:如果你打算使用 RSA 或 ECDSA 等数字签名算法编码/解码 token,就需要安装 cryptography 库。从源码看,需要 cryptography 的算法在 jwt/algorithms.py 中集中声明为 requires_cryptography 集合:
requires_cryptography = {
"RS256", "RS384", "RS512",
"ES256", "ES256K", "ES384", "ES521", "ES512",
"PS256", "PS384", "PS512",
"EdDSA",
}
对照 docs/algorithms.rst 的算法清单,可以给出如下对应关系:
| 算法族 | 具体算法 | 是否需要 cryptography |
|---|---|---|
| HMAC(默认) | HS256、HS384、HS512 | 否 |
| RSA(RSASSA-PKCS1-v1_5) | RS256、RS384、RS512 | 是 |
| RSA(RSASSA-PSS) | PS256、PS384、PS512 | 是 |
| ECDSA | ES256、ES256K、ES384、ES512、ES521 | 是 |
| EdDSA(Ed25519/Ed448) | EdDSA | 是 |
换句话说:只签发和校验 HS256 token 的应用可以不装 cryptography;一旦要使用非对称算法,就必须安装它。
三、推荐写法:pip install pyjwt[crypto]
官方文档给出的推荐命令是:
$ pip install pyjwt[crypto]
其中 <a href="https://link.gitcode.com/i/04689ab1d9b172121adc8671275a6edc" target="_blank">crypto] 是 PyJWT 在 pyproject.toml 中声明的可选依赖(extra),其内容在 [pyproject.toml 中定义:
[project.optional-dependencies]
crypto = [
"cryptography>=3.4.0",
]
即 pyjwt<a href="https://link.gitcode.com/i/4f8980adf95294a2f54222153db98609" target="_blank">crypto] 等价于同时安装 pyjwt 与 cryptography>=3.4.0。仓库在 [CHANGELOG.rst 中记录了这一写法被正式文档化并推荐的历史(PR #426,官方明确“Document (and prefer) pyjwt[crypto] req format”)。
文档特别强调:在项目的 requirements 文件中应优先使用 pyjwt[crypto] 这种整体写法,而不是单独写一行 cryptography。原因是:单独成行的 cryptography 依赖在后续维护中可能被误判为“不再被使用”而随手删除,导致运行期才暴露出缺失;而 pyjwt[crypto] 把“这个项目需要带加密能力的 PyJWT”这一意图绑定在同一个声明上,语义清晰、不易误删。
两种写法的对比:
# 推荐:需求意图一目了然
pyjwt[crypto]
# 不推荐:cryptography 可能被误判为冗余依赖
pyjwt
cryptography>=3.4.0
四、不装 cryptography 会发生什么?
了解“缺失时”的行为有助于判断安装是否完整。从源码结构看,PyJWT 通过 jwt/algorithms.py 顶部的 try/except ModuleNotFoundError 探测 cryptography 是否可用,并用模块级布尔量 has_crypto 标记结果:
- 导入成功 →
has_crypto = True,get_default_algorithms()(jwt/algorithms.py)才会把 RS*、ES*、PS*、EdDSA 等非对称算法注册进默认算法表;HMAC 与none算法始终可用。 - 导入失败 →
has_crypto = False,非对称算法全部不可用。
当你尝试使用未安装的算法时,jwt/api_jws.py 的 get_algorithm_by_name() 会抛出明确的错误提示:
raise NotImplementedError(
f"Algorithm '{alg_name}' could not be found. Do you have cryptography installed?"
)
仓库的测试也专门覆盖了这一场景,例如 tests/test_api_jwk.py 中的 test_missing_crypto_library_good_error_message 与 test_missing_crypto_library_raises_missing_cryptography_error,分别在 no_crypto_required 装饰器标记的无 cryptography 环境下验证了错误信息中包含 cryptography 字样。CI 矩阵(tox.ini)中同时包含 crypto 与 nocrypto 两套环境,正是为了持续保证“有/无 cryptography”两种安装形态都行为正确。
五、安装后的验证:快速冒烟测试
安装完成后,可以在 Python 交互环境里做一次冒烟测试。最简单的验证方式是分别尝试一个 HS256 和一个 RS256 操作:
>>> import jwt
>>> # 不依赖 cryptography 的 HMAC 路径
>>> jwt.decode(jwt.encode({"ok": True}, "secret", algorithm="HS256"), "secret", algorithms=["HS256"])
{'ok': True}
>>> # 依赖 cryptography 的 RSA 路径:未安装 cryptography 时会抛 NotImplementedError
>>> import jwt
>>> jwt.encode({"some": "payload"}, b"-----BEGIN RSA PRIVATE KEY-----\n...", algorithm="RS256")
若第二条命令抛出 NotImplementedError: Algorithm 'RS256' could not be found. Do you have cryptography installed?,则说明当前环境的 PyJWT 缺少 cryptography 依赖,需要执行 pip install pyjwt<a href="https://link.gitcode.com/i/717f9db5018c73ada2a1f61c010430d8" target="_blank">crypto] 补齐。RSA 的完整可用示例可参考 [docs/usage.rst(RS256)、docs/usage.rst(PS256)、docs/usage.rst(EdDSA)与 docs/usage.rst(ES256)。
此外,cryptography 还在以下场景发挥额外作用,安装后一并可用:
- 从 PEM/SSH 格式加载 RSA、EC、OKP(Ed25519/Ed448)密钥(见 jwt/algorithms.py 中
RSAAlgorithm.prepare_key的实现); - 使用带口令的私钥(
load_pem_private_key(..., password=...),用法见 docs/usage.rst); - 从 JWKS 端点解析 RSA/EC/OKP JWK 密钥(
PyJWK/PyJWKSet/PyJWKClient,见 tests/test_api_jwk.py 与 jwt/api_jwk.py)。
六、进阶:从源码安装与开发环境(可选)
普通使用者用 pip 安装即可,无需从源码构建。如果你希望从当前仓库源码入手,可以关注 tox.ini 与 pyproject.toml 中的开发配置:
- 依赖分组:
dev、docs、tests三组依赖定义在 pyproject.toml,其中dev已包含cryptography>=3.4.0; - 测试命令:
tox默认矩阵覆盖 Python 3.9–3.15 与 CPython/PyPy 的crypto、nocrypto两种形态(tox.ini); - 文档构建:
tox -e docs会运行sphinx-build(tox.ini),文档源码位于 docs/index.rst 及同目录各.rst文件。
总结
PyJWT 的安装核心就两条命令,按需选择:
$ pip install pyjwt # 只用 HS* 对称签名时的最小安装
$ pip install pyjwt[crypto] # 使用 RS*/ES*/PS*/EdDSA 非对称算法时的推荐安装
在 requirements 文件中请坚持使用 pyjwt[crypto] 的整行写法,避免单独声明 cryptography 造成后续被误删。安装后可用一次 RS256 编解码作为冒烟测试,确认非对称算法链路完整可用。