json-repair

library0.63.4pypypi✓ verified 24d ago

json-repair is a Python library designed to automatically fix malformed or invalid JSON strings, making them parseable by standard JSON parsers. It addresses common issues like missing quotes, trailing commas, and incomplete structures, making it particularly useful for processing data from less strict sources like LLMs or web scraping. The library is actively maintained with frequent minor releases addressing bug fixes and performance improvements. The current version is 0.58.7.

serialization data

pip install json-repair

github ↗package ↗

INSTALL

IMPORT

SIG · JSON-REPAIR

json-repair

serializationpythonv0.63.4

Install

1.6s avg

Import

69ms

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.63.4 · 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.072s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.066s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

repair_json

✓ from json_repair import repair_json

loads

✓ from json_repair import loads

✗ import json_repair; repaired_data = json_repair.repair_json_string(my_string)

The primary repair function is `repair_json`. `loads` is a convenient drop-in replacement for `json.loads` that includes repair logic. Directly calling a non-existent `repair_json_string` method is a common typo.

The quickstart demonstrates repairing a malformed JSON string using both `repair_json` to get a valid string and `loads` for direct parsing into a Python object.

from json_repair import repair_json, loads import json broken_json_string = """{ 'name': 'Alice', age: 30, 'isStudent': True, 'hobbies': ['reading', 'gaming',], }""" # Using repair_json to get a fixed JSON string repaired_string = repair_json(broken_json_string) print(f"Repaired string: {repaired_string}") parsed_data = json.loads(repaired_string) print(f"Parsed data (using json.loads): {parsed_data}") # Using loads for direct parsing to Python object # This method already includes the repair logic internally parsed_data_direct = loads(broken_json_string) print(f"Parsed data (using json_repair.loads): {parsed_data_direct}")

json-repair --version

Debug

Known issues

gotchaThe `schema_repair_mode='salvage'` option, introduced in v0.58.0, prioritizes data recovery but might yield an output that is not fully compliant with the provided JSON schema. There have been past regressions (fixed in v0.58.4) where `salvage` mode repaired less aggressively than `standard` mode.

fix

Carefully review the output when using `schema_repair_mode='salvage'`. Consider if `standard` mode or manual post-processing is more appropriate for strict schema adherence. Always test with representative malformed inputs.

affects: >=0.58.0

breakingStarting from v0.57.1, valid JSON input that does not conform to an optionally provided JSON schema may be *coerced* to match the schema's types (e.g., a string '1' might become an integer 1). This can alter data types in ways that might be unexpected if strict validation without coercion was desired.

fix

Be aware of potential type coercions when providing a `schema` parameter. If strict validation without modification is needed, consider validating the output separately or using an older version if possible, though this is not recommended. The library's focus is on repair and usability.

affects: >=0.57.1

gotchaBy default, `json-repair` first attempts to parse the input using Python's standard `json.loads()`. Only if this fails does it proceed with its repair logic. Explicitly wrapping `json.loads()` in a `try...except` block before calling `json_repair.repair_json()` is redundant and an anti-pattern.

fix

Simply call `json_repair.repair_json()` or `json_repair.loads()`. If you are certain the input is invalid and want to skip the initial `json.loads()` attempt for performance reasons, pass `skip_json_loads=True`.

affects: All versions

gotchaThe `strict=True` parameter changes the repair behavior to be more validation-oriented. In strict mode, the parser raises a `ValueError` for structural issues like duplicate keys, missing separators, or multiple top-level elements, rather than attempting to fix them. This results in less aggressive repair.

fix

Use `strict=True` when you need stricter validation and clear error messages for structural problems, accepting that some malformed JSON that would otherwise be repaired will instead raise an error. For maximum repair capability, omit `strict=True` (default is `False`).

affects: All versions

gotchaVersions prior to v0.58.5 had significantly lower parser performance, especially for common JSON strings. v0.58.5 introduced a 60% improvement.

fix

Upgrade to version 0.58.5 or newer for substantial performance gains when repairing JSON.

affects: <0.58.5

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'json_repair'

The Python package is installed via `pip install json-repair` using a hyphen, but imported in code using an underscore (`import json_repair`).

fix

Ensure the package is installed as `pip install json-repair` and imported as `import json_repair`.

TypeError: expected string or bytes-like object

The `repair_json` or `loads` function was called with an argument that is not a string or bytes-like object (e.g., an integer, None, or a list).

fix

Ensure the input passed to `json_repair.repair_json()` or `json_repair.loads()` is always a string. Convert the input to a string using `str()` if necessary.

ValueError (when using strict=True)

When `strict=True` is enabled for `repair_json` or `loads`, the library enforces stricter JSON validation rules and will raise a `ValueError` if the input contains structural issues like duplicate keys, missing separators, or multiple top-level elements, which cannot be strictly repaired.

fix

Either ensure the input JSON adheres to strict validity, or remove `strict=True` from the function call to allow `json-repair` to perform more lenient, heuristic-based repairs.

json.JSONDecodeError

While `json-repair` is designed to prevent this by fixing malformed JSON, users might still encounter `json.JSONDecodeError` if they incorrectly apply the library, for instance, by trying to parse the original malformed string with `json.loads` *after* a failed `json_repair` attempt (instead of using `json_repair.loads` which includes `json.loads` internally), or if `json-repair` cannot fix severely corrupted JSON and `json.loads` is then called on the still-invalid output.

fix

Prefer using `json_repair.loads(json_string)` directly, as it automatically attempts standard `json.loads()` first and falls back to repair if decoding fails, eliminating the need for a manual `try-except` block for `json.JSONDecodeError`.

Upgrade

Version history

0.63.4latest on PyPI · released Aug 25, 2026

Audit

Dependencies

pythonrequiredRequired Python version.

Agent activity

14 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mangiucugna/json_repair ↗

packagehttps://pypi.org/project/json-repair/ ↗