json5

library0.15.0pypypi✓ verified 25d ago

The `json5` library is a Python implementation of the JSON5 data format, which extends standard JSON to be more human-friendly, allowing features like JavaScript-style comments, unquoted object keys, trailing commas in objects and arrays, and single-quoted or multi-line strings. It aims to mirror the API of Python's built-in `json` module for ease of use. The current version is 0.14.0, and it maintains a regular release cadence.

serialization

pip install json5

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · JSON5

json5

serializationpythonv0.15.0

Install

1.7s avg

Import

14ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.15.0 · 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.014s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.014s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

json5

✓ import json5

The library typically exposes functions like `load`, `loads`, `dump`, `dumps` directly under the `json5` module, mimicking the standard `json` library.

Demonstrates parsing JSON5 strings using `json5.loads()` and serializing Python objects to JSON5 strings using `json5.dumps()`. The API closely resembles Python's standard `json` module.

import json5 # Parse a JSON5 string with comments and trailing commas config_string = """ { // Application settings name: 'my-app', version: '1.0.0', features: [ 'comments', 'trailing commas', ], } """ config = json5.loads(config_string) print(f"App Name: {config['name']}") # Convert a Python object to a JSON5 string data = { 'name': 'another-app', 'debug': True, 'ports': [3000, 3001], } json5_string = json5.dumps(data, indent=2, quote_keys=False, trailing_commas=True) print("\nSerialized JSON5:") print(json5_string) # Example of reading/writing a file (assuming a config.json5 exists) # with open('config.json5', 'w') as f: # json5.dump(data, f, indent=2) # # with open('config.json5', 'r') as f: # loaded_config = json5.load(f) # print(f"\nLoaded from file: {loaded_config['name']}")

json5 --version

Debug

Known issues

gotchaPerformance Warning: `json5` is significantly slower than Python's built-in `json` module (especially the C-optimized version). It can be 1000-6000x slower for parsing and 200x slower than the pure Python `json` module. Consider performance implications for high-throughput applications.

fix

For performance-critical scenarios, process JSON5 during development/configuration loading and convert to standard JSON for runtime if possible, or use the `json` module if JSON5 features are not strictly needed.

affects: All versions

breakingUnsupported `cls` argument: The `cls` keyword argument, commonly used in `json.load()`, `json.loads()`, `json.dump()`, and `json.dumps()` for custom `JSONDecoder` or `JSONEncoder` subclasses, is not supported by `json5` due to a different parsing approach.

fix

Custom deserialization/serialization logic needs to be implemented externally or by using `object_hook` and `default` arguments, which *are* supported, if applicable. Direct subclassing of internal `json5` classes is not an option.

affects: All versions

gotchaEncoding in `dump()` is ignored: The `encoding` method to `dump()` is ignored, and unicode strings are always returned. This differs from the behavior of the standard `json` module.

fix

Be aware that `dump()` will always produce Unicode output. Handle encoding to specific byte streams explicitly after getting the Unicode string if non-UTF-8 output is required.

affects: All versions

gotchaDuplicate keys handling: By default, `json5.load()` and `json5.loads()` allow duplicate object keys, with the last key-value pair taking precedence (standard JSON behavior). However, you can explicitly reject duplicates by passing `allow_duplicate_keys=False`. This is a notable difference in explicit control compared to the standard `json` module.

fix

To enforce uniqueness of keys in parsed JSON5 documents, use `json5.loads(data, allow_duplicate_keys=False)` or `json5.load(file, allow_duplicate_keys=False)`.

affects: All versions

gotchaNot a full JavaScript parser: The `json5` library is designed to parse JSON5 documents, not arbitrary JavaScript code. Attempting to parse non-JSON5 JavaScript syntax (e.g., bare integers as object keys, or complex expressions) will result in parsing errors.

fix

Ensure input adheres strictly to the JSON5 specification. If arbitrary JavaScript parsing is needed, a dedicated JavaScript parser library should be used.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'json5'

The `json5` Python package is not installed in the current environment.

fix

Install the `json5` library using pip: `pip install json5`.

json5.json5.Json5DecodeError: Unexpected token

The input JSON5 string contains a syntax error that even the more lenient JSON5 parser cannot handle, such as a malformed structure, an invalid unquoted key, or an unexpected character.

fix

Review the JSON5 string for syntax errors. Ensure that unquoted keys are valid JavaScript identifiers, and check for missing commas, unclosed strings, or other structural issues.

json5.json5.Json5DecodeError: Invalid control character at: line X column Y (char Z)

The JSON5 input string contains unescaped control characters (e.g., raw newline, tab, or carriage return characters) within a string literal that must be escaped.

fix

Replace unescaped control characters within string literals with their corresponding JSON escape sequences (e.g., `\n` for newline, `\t` for tab, `\r` for carriage return).

Upgrade

Version history

0.15.0latest on PyPI · released Jun 19, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

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

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

changeloghttps://github.com/dpranke/pyjson5/blob/master/README.md ↗