# python-jose for JWS, JWE, JWK, and JWA in Python

> python-jose implements the JOSE standards for signing, encrypting, and managing JSON-based cryptographic content in Python. Its main engineering choice is a selectable cryptographic backend, while native-python cannot process certificates.

**mpdavis/python-jose** — A JOSE implementation in Python

- Repository: https://github.com/mpdavis/python-jose
- Stars: 1,759 · Forks: 272
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/mpdavis-python-jose

## What python-jose covers

python-jose addresses the cryptographic operations described by the JavaScript Object Signing and Encryption family. The README names JSON Web Signature, JSON Web Encryption, JSON Web Key, and JSON Web Algorithms. These technologies cover signing or encrypting content, working with JSON-based keys, and selecting the algorithms used for those operations.

The library is aimed at Python applications that need to create or process signed and encrypted JSON documents. JWT usage is one documented part of this broader scope. The public example imports `jose.jwt`, passes a claims dictionary and secret to `jwt.encode`, and later decodes the resulting token. This makes python-jose relevant to authentication tokens and other data formats built around JOSE, although the README does not limit the library to authentication.

Algorithm choice remains in application code. The encoding example names `HS256`, while the decoding call supplies an accepted algorithm list containing `HS256`. That separation matters. Encoding establishes how a token was produced, but the verifier still receives an explicit algorithm policy when it calls `jwt.decode`.

The README says the complete set of algorithm permutations is large, then focuses on the smaller set expected in most applications. It does not publish a complete algorithm compatibility matrix. An engineer choosing the library for a specific operation should therefore verify that operation and its algorithm in the project documentation rather than assuming every JOSE algorithm is available through every call path.

## python-jose backend architecture

python-jose has three documented cryptographic backends: `cryptography`, `pycryptodome`, and `native-python`. The `cryptography` backend delegates cryptographic operations to `pyca/cryptography`. The `pycryptodome` backend uses `pycryptodome`. The native backend uses `python-rsa` and `python-ecdsa` for its cryptographic work.

Backend selection is tied to package installation. If no backend extra is selected, python-jose installs the native-python backend. If another backend is present, it takes precedence. The README specifically recommends the `cryptography` backend and says it is selected over the others when installed.

This design separates python-jose's JOSE-level interfaces from the packages performing cryptographic operations. The repository contains a `jose` directory, while dependency declarations are managed through files including `requirements.txt`, `setup.cfg`, and `setup.py`. Based on that layout, application code uses the public `jose` package while the installed backend supplies the underlying primitives. The README does not describe an internal backend-selection API or configuration file, so backend choice should be controlled through installation rather than an invented runtime setting.

The README states that, unless otherwise noted, all backends support all operations. Certificate processing is the explicit exception documented for native-python. The statement is broad, but it should not be read as a detailed guarantee for each algorithm and each backend.

## Installing the recommended backend

The README recommends installing python-jose with the `cryptography` extra. This installation selects `pyca/cryptography` as the cryptographic implementation when that backend is present.

```bash
pip install python-jose[cryptography]
```

The native-python dependencies are installed in either case because the README says setuptools complexities cause them to remain available even when another backend is selected. For the `cryptography` backend, the README identifies `rsa`, `ecdsa`, and `pyasn1` as unused dependencies. It recommends removing unnecessary dependencies in production.

That recommendation needs careful packaging treatment. An ordinary installation does not document an automatic removal step for packages inherited through python-jose's installation structure. Based on the README, a production image should contain the backend required by the application without retaining unnecessary native-backend packages. The README does not name a package-manager command for removing them, so this article does not provide one.

An alternative installation uses the `pycryptodome` extra:

```bash
pip install python-jose[pycryptodome]
```

The README lists `rsa` as unused for that backend. Installing without an extra provides the native-python implementation:

```bash
pip install python-jose
```

These commands come directly from the README's backend installation examples. The project does not document operating-system-specific installation steps or a pinned production installation command.

## Encoding and decoding the first JWT

The README's first use imports the `jwt` module from `jose`. Encoding accepts a dictionary, a secret, and an explicit algorithm. The first example creates claims containing `key` and `value` and signs them with `HS256`.

```python
from jose import jwt

token = jwt.encode({'key': 'value'}, 'secret', algorithm='HS256')
```

The result is a compact token made from dot-separated encoded segments. The README displays a token beginning with a header that identifies `HS256` and `JWT`, followed by the encoded claims and a signature segment.

Decoding uses the token, secret, and an explicit list of accepted algorithms:

```python
jwt.decode(token, 'secret', algorithms=['HS256'])
```

The documented result is a dictionary containing `key` and `value`. This two-step flow shows the intended basic division of responsibility. The encoder names the algorithm used to produce the token, and the decoder supplies the set of algorithms the application accepts. The README example does not show expiration handling, audience validation, issuer validation, certificate use, or error handling.

The sample secret is a short string intended to illustrate the API. The README does not provide key generation, storage, rotation, or production key-management guidance. Those concerns must remain part of the surrounding application and security review.

## Native-python certificate limitation

The native-python backend cannot process certificates. This limitation comes directly from the README, and it gives certificate-dependent applications a clear backend boundary. Selecting an installation without a backend extra is therefore a poor fit when the application expects certificate processing through that backend.

The README does not provide a certificate example, configuration key, or alternative call that bypasses the limitation. It also does not explain which certificate formats the other backends accept. An application can avoid the stated native-python restriction by installing another documented backend, but it still needs to verify its particular certificate type and operation. `pyca/cryptography` and `pycryptodome` should not be treated as interchangeable without that check.

There is another operational concern. The native-python backend is always installed even when another backend is selected. Unused dependencies are documented for both non-native choices. This can produce an environment with the recommended backend active while packages for native-python operations remain present.

The README recommends removing unnecessary dependencies in production, but it does not document a supported uninstall procedure, dependency lock file, or deployment configuration. It also does not document rollback or migration between backends. Those are adoption checks rather than omissions that can safely be filled with assumptions.

## PyJWT history and alternative design choices

The README states that python-jose was originally based heavily on work from the PyJWT project. It documents no feature comparison or compatibility claims between the two projects. The README does not provide a feature comparison, compatibility matrix, migration guide, or statement that either project supports a particular feature the other lacks.

For a team choosing between python-jose and a JWT-focused library, the documented basis for comparison is therefore limited. python-jose explicitly presents the wider JOSE family, including JWS, JWE, JWK, and JWA. A library limited by the caller to JWT operations may have fewer installation choices to evaluate, but the README does not document those alternatives closely enough to claim specific advantages for them.

Within python-jose, the three backends offer a more concrete design choice. `cryptography` uses `pyca/cryptography` and is the recommended option. `pycryptodome` uses `pycryptodome`. Native-python uses `python-rsa` and `python-ecdsa`, but cannot process certificates. Each route changes the dependency set and may affect deployment packaging.

The repository includes `tests/`, `tox.ini`, `pytest.ini`, and a GitHub Actions workflow. These entries show test and CI assets, but neither their presence nor repository activity proves compatibility with an application's particular Python version or deployment environment. No conclusion about performance is possible from the files and README alone.

## Maintenance, releases, and upgrade checks

The repository is not archived. Its last push was on 2026-04-14. The release list records version 3.5.0 on 2025-05-28, version 3.4.0 on 2025-02-14, and version 3.3.0 on 2021-06-05. Release 3.3.0 is also the version identified in the README as the point from which python-jose implements three cryptographic backends.

The repository contains `CHANGELOG.md` and `VERSIONING.rst`, so release and change information has dedicated files. The README does not summarize those files, and it does not document an upgrade procedure. It also does not provide a supported Python version range, dependency constraints for production, or a rollback process. Those details require direct inspection before changing an installed version.

The project is distributed under the MIT license. That is the declared repository license, not a guarantee that every dependency uses the same terms. License review should cover the packages actually installed with the chosen backend. This article does not provide legal advice or interpret license obligations beyond identifying the project's stated license.

## Conclusion

Adopt python-jose when an application needs a Python implementation covering JWS, JWE, JWK, or JWA and can select a backend deliberately. Do not use its native-python backend when certificate processing is required, and do not assume that all backends have the same dependency set. Verify the backend selection, required algorithms, and certificate behavior first. The repository's last push was on 2026-04-14.

## FAQ

### How do I install python-jose with the recommended cryptographic backend?

Install `python-jose[cryptography]`. The README identifies the `cryptography` backend as the recommended one and says it takes precedence when other backends are present.

### Which algorithms does python-jose support?

python-jose covers operations defined across JWS, JWE, JWK, and JWA. The README does not provide a complete algorithm matrix, so check the documentation for the exact algorithm required by an application.

### Can the native-python backend process certificates?

No. The README explicitly states that the native-python backend cannot process certificates.

### How does python-jose encode and decode a JWT?

Pass claims, a key, and an algorithm to `jwt.encode`. Then pass the token, key, and an explicit `algorithms` list to `jwt.decode`. The documented example uses `HS256`.

## Sources

- [Issues](https://github.com/mpdavis/python-jose/issues)
- [License: MIT](https://github.com/mpdavis/python-jose/blob/master/LICENSE)
- [mpdavis/python-jose on GitHub](https://github.com/mpdavis/python-jose)
- [README](https://github.com/mpdavis/python-jose/blob/master/README.md)
- [Releases](https://github.com/mpdavis/python-jose/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mpdavis-python-jose