pyjson5

library2.0.1pypypi✓ verified 26d ago

PyJSON5 is a high-performance JSON5 serializer and parser library for Python 3, implemented in Cython. It extends the standard JSON format with features like comments, unquoted keys, and trailing commas, making it ideal for human-editable configuration files. This library is actively maintained, with frequent updates and a current stable version of 2.0.0.

serialization

pip install pyjson5

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYJSON5

pyjson5

serializationpythonv2.0.1

Install

1.8s avg

Import

40ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.042s · 21.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.038s · 19MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loads, dumps, load, dump

✓ import pyjson5 # Use pyjson5.loads, pyjson5.dumps, etc.

✗ import json5

The PyPI package `json5` is a different, pure-Python implementation. This library (pyjson5, the Cython one) exposes its functions directly under the `pyjson5` module. Using `import json5` will import the other library if installed.

This quickstart demonstrates how to load JSON5 data from a string using `pyjson5.loads` and dump Python objects back to a JSON5 string using `pyjson5.dumps`. It also shows reading from and writing to file-like objects using `pyjson5.load` and `pyjson5.dump` respectively. Note the use of `io.StringIO` for in-memory file operations.

import pyjson5 import io json5_data = """ { // This is a comment name: 'Project Alpha', version: 1.0.0, features: [ 'comments', 'trailing commas', ], config: { key: 'value', }, // Trailing comma } """ # Load from a string data = pyjson5.loads(json5_data) print(f"Loaded data: {data}") # Dump to a string output_json5 = pyjson5.dumps(data, indent=2) print(f"\nDumped JSON5:\n{output_json5}") # Load from a file-like object (StringIO acts like a file) file_like_obj_read = io.StringIO(json5_data) file_data = pyjson5.load(file_like_obj_read) print(f"\nLoaded from file-like object: {file_data}") # Dump to a file-like object file_like_obj_write = io.StringIO() pyjson5.dump(data, file_like_obj_write, indent=2) print(f"\nDumped to file-like object:\n{file_like_obj_write.getvalue()}")

json5 --version

Debug

Known issues

breakingIn `pyjson5` v2.0.0, the `dump()` function now consistently writes `str` (Unicode) instead of `bytes` to file-like objects. This is a change from previous versions and can lead to `TypeError: a bytes-like object is required, not 'str'` if the target file object is opened in binary write mode (`'wb'`).

fix

Ensure that file-like objects passed to `pyjson5.dump()` are opened in text write mode (e.g., `open('file.json5', 'w')`) rather than binary write mode (`'wb'`).

affects: >=2.0.0

breakingStarting with `pyjson5` v2.0.0, the library explicitly requires Python 3.8 or later. Versions prior to `v1.6.8` supported Python 3.5+, and `v1.6.8` raised the minimum to Python 3.7+.

fix

Upgrade your Python environment to version 3.8 or newer to use `pyjson5` v2.0.0 and subsequent releases. If backward compatibility with older Python versions is required, use `pyjson5` v1.x.

affects: >=2.0.0

gotchaUnlike Python's standard `json` module, `pyjson5` does not support the `cls` keyword argument for custom `JSONDecoder` or `JSONEncoder` subclasses in its `load`, `loads`, `dump`, or `dumps` functions. This is due to its Cython-based parsing and serialization approach.

fix

Instead of `cls`, use the `default` keyword argument in `dumps` or `dump` for custom serialization of unsupported types. For custom deserialization, manual post-processing of the loaded Python object is often required.

affects: All versions

gotchaJSON5 is designed for human-editable configuration files, allowing features like comments and unquoted keys. It is generally not recommended for strict machine-to-machine communication, where the more rigid standard JSON format is often preferred due to broader tooling support and stricter validation.

fix

Consider the use case: if machine-to-machine interoperability is paramount, use Python's built-in `json` module. If human readability and maintainability of configuration files are the priority, `pyjson5` is a suitable choice.

affects: All versions

gotchaBy default, `pyjson5.load()` and `pyjson5.loads()` allow duplicate keys within an object (dictionary) in the JSON5 input. When duplicate keys are present, the last encountered value for that key will override previous ones.

fix

To enforce strict parsing and disallow duplicate keys, pass `allow_duplicate_keys=False` to the `load()` or `loads()` functions. For example: `pyjson5.loads(json5_string, allow_duplicate_keys=False)`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyjson5'

The 'pyjson5' library is not installed in your current Python environment.

fix

Install the library using pip: `pip install pyjson5`

pyjson5.Json5IllegalCharacter: An unexpected character was encountered

The input string or file provided to `pyjson5.decode()` or `pyjson5.loads()` contains invalid JSON5 syntax, such as an unexpected character, missing comma, or unquoted key that isn't a valid ECMAScript identifier.

fix

Carefully review the JSON5 input for syntax errors, ensuring correct object/array delimiters, proper key quoting, and valid characters. Use a JSON5 linter or validator to pinpoint the exact location of the error.

TypeError: An argument had a wrong type

A function in `pyjson5` was called with an argument of an incorrect or unsupported Python type, such as attempting to encode an unstringifiable object without a custom default handler, or providing non-string data to a decoding function that expects a string.

fix

Check the `pyjson5` function's documentation to understand the expected types for its arguments and ensure your data matches those requirements. For encoding complex types, provide a `default` function to handle custom serialization.

Upgrade

Version history

2.0.1latest on PyPI · released May 15, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/Kijewski/pyjson5 ↗

packagehttps://pypi.org/project/pyjson5/ ↗

docshttps://pyjson5.readthedocs.io/ ↗

changeloghttps://github.com/Kijewski/pyjson5/blob/main/CHANGELOG.md ↗