# json-repair

> A package to repair broken json strings

- **URL**: https://www.freshcrate.ai/projects/json-repair
- **Author**: pypi
- **Category**: Developer Tools
- **Latest version**: `v0.60.1` (2026-06-03)
- **License**: Unknown
- **Source**: https://github.com/mangiucugna/json_repair/issues
- **Homepage**: https://pypi.org/project/json-repair/
- **Language**: Python
- **GitHub**: 4,672 stars, 187 forks
- **Registry**: pypi (`json-repair`)
- **Tags**: `json`, `llm`, `parser`, `pypi`, `repair`

## Description

[![PyPI](https://img.shields.io/pypi/v/json-repair)](https://pypi.org/project/json-repair/)
![Python version](https://img.shields.io/badge/python-3.10+-important)
[![PyPI downloads](https://img.shields.io/pypi/dm/json-repair)](https://pypi.org/project/json-repair/)
[![PyPI Downloads](https://static.pepy.tech/badge/json-repair)](https://pepy.tech/projects/json-repair)
[![Github Sponsors](https://img.shields.io/github/sponsors/mangiucugna)](https://github.com/sponsors/mangiucugna)
[![GitHub Repo stars](https://img.shields.io/github/stars/mangiucugna/json_repair?style=flat)](https://github.com/mangiucugna/json_repair/stargazers)

English | [中文](README.zh.md)

This simple package can be used to fix an invalid json string. To know all cases in which this package will work, check out the unit test.

![banner](banner.png)

---

# Think about sponsoring this library!
This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider becoming a sponsor via this link: https://github.com/sponsors/mangiucugna

## Premium sponsors
- [Icana-AI](https://github.com/Icana-AI) Makers of CallCoach, the world's best Call Centre AI Coach. Visit [https://www.icana.ai/](https://www.icana.ai/)
- [mjharte](https://github.com/mjharte)

---

# Demo
If you are unsure if this library will fix your specific problem, or simply want your json validated online, you can visit the demo site on GitHub pages: https://mangiucugna.github.io/json_repair/

Or hear an [audio deepdive generate by Google's NotebookLM](https://notebooklm.google.com/notebook/05312bb3-f6f3-4e49-a99b-bd51db64520b/audio) for an introduction to the module

---

# Motivation
Some LLMs are a bit iffy when it comes to returning well formed JSON data, sometimes they skip a parentheses and sometimes they add some words in it, because that's what an LLM does.
Luckily, the mistakes LLMs make are simple enough to be fixed without destroying the content.

I searched for a lightweight python package that was able to reliably fix this problem but couldn't find any.

*So I wrote one*

# Supported use cases

### Fixing Syntax Errors in JSON

- Missing quotes, misplaced commas, unescaped characters, and incomplete key-value pairs.
- Missing quotation marks, improperly formatted values (true, false, null), and repairs corrupted key-value structures.

### Repairing Malformed JSON Arrays and Objects

- Incomplete or broken arrays/objects by adding necessary elements (e.g., commas, brackets) or default values (null, "").
- The library can process JSON that includes extra non-JSON characters like comments or improperly placed characters, cleaning them up while maintaining valid structure.

### Auto-Completion for Missing JSON Values

- Automatically completes missing values in JSON fields with reasonable defaults (like empty strings or null), ensuring validity.

# How to use

Install the library with pip

    pip install json-repair

then you can use use it in your code like this

    from json_repair import repair_json

    good_json_string = repair_json(bad_json_string)
    # If the string was super broken this will return an empty string


You can use this library to completely replace `json.loads()`:

    import json_repair

    decoded_object = json_repair.loads(json_string)

or just

    import json_repair

    decoded_object = json_repair.repair_json(json_string, return_objects=True)

### Avoid this antipattern
Some users of this library adopt the following pattern:

    obj = {}
    try:
        obj = json.loads(string)
    except json.JSONDecodeError as e:
        obj = json_repair.loads(string)
        ...

This is wasteful because `json_repair` already does that strict `json.loads()` check for you by default. The normal flow is:

- try the built-in `json.loads()` / `json.load()` first
- if that succeeds, return the decoded object
- if that fails, run the repair parser

Use the default call unless you explicitly want to skip that initial validation step:

```python
import json_repair

decoded_object = json_repair.loads(json_string)
```

### Read json from a file or file descriptor

JSON repair provides also a drop-in replacement for `json.load()`:

    import json_repair

    try:
        file_descriptor = open(fname, 'rb')
    except OSError:
        ...

    with file_descriptor:
        decoded_object = json_repair.load(file_descriptor)

and another method to read from a file:

    import json_repair

    try:
        decoded_object = json_repair.from_file(json_file)
    except OSError:
        ...
    except IOError:
        ...

Keep in mind that the library will not catch any IO-related exception and those will need to be managed by you

### Non-Latin characters

When working with non-Latin characters (such as Chinese, Japanese, or Korean), you need to pass `ensure_ascii=False` to `repair_json()` in order to preserve the non-Latin characters in the output.

Here's an example using Chinese character

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v0.60.1` | 2026-06-03 | High | # Added - A potential infinite loop in schema resolution could cause an application using the library to crash if the schema was self referential  # Support this project  `json_repair` is maintained as a side project and stays free for everyone.  If it saves you debugging time, helps you handle LLM-generated JSON, or is part of your production workflow, please consider: - starring the repository to help more developers find it - sharing it with teams working with unreliable JSON output |
| `v0.59.10` | 2026-05-14 | High | # Fixed - Fixed a parser-path repair bug where balanced brace groups inside string values, such as LaTeX fragments like `\frac{x^2}{m}`, could be mistaken for object structure when a later inline JSON-like snippet appeared in the same string. - Improved preservation of malformed-but-string-intended explanations containing inline literals such as `{"blank_1": "5"}` without splitting the surrounding object.  # Support this project  `json_repair` is maintained as a side project and stays free |
| `v0.59.6` | 2026-05-10 | High | # Fixed - Fix #194, the presence of a bracket in a comment line would mess up the repair  # Support this project  `json_repair` is maintained as a side project and stays free for everyone.  If it saves you debugging time, helps you handle LLM-generated JSON, or is part of your production workflow, please consider: - starring the repository to help more developers find it - sharing it with teams working with unreliable JSON output - sponsoring the project here: https://github.com/sponso |
| `v0.59.5` | 2026-04-24 | High | # Fixed - Fix `load(fd)` so repair starts from the current position of the file object.  # Performance - Preserve schema validator cache hits across repeated schema repairs. - Avoid parser setup when valid JSON can return through the `json.loads` fast path. - Reduce parser hot-path overhead by trimming context manager usage and object/string state allocations.  # Support this project  `json_repair` is maintained as a side project and stays free for everyone.  If it saves you debugging time, help |
| `0.59.4` | 2026-04-21 | Low | Imported from PyPI (0.59.4) |
| `v0.59.4` | 2026-04-15 | High | # Fixed - Fix #193, improve handling of various exceptions and corner cases related to code fences when the LLM outputs code  # Think about sponsoring this library!  This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider offering me a beer via this link: https://github.com/sponsors/mangiucugna |
| `v0.59.4` | 2026-04-15 | Medium | # Fixed - Fix #193, improve handling of various exceptions and corner cases related to code fences when the LLM outputs code  # Think about sponsoring this library!  This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider offering me a beer via this link: https://github.com/sponsors/mangiucugna |
| `v0.59.3` | 2026-04-14 | Medium | # Fixed - Fix #192, preserve literal fenced snippets in multiline strings - Throw a `ValueError` in case the library hits a `RecursionError`  # Think about sponsoring this library!  This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider offering me a beer via this link: https://github.com/sponsors/mangiucugna |
| `v0.59.2` | 2026-04-11 | Medium | # Fixed - Fix #189, when an LLM emits unescaped JSON like `{"blank_1": "..."}` inside a quoted explanation string. Previously the parser could split the parent string, invent extra object members, or even change the top-level shape when another member followed.  # Think about sponsoring this library!  This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider offering me a beer via this link: https://git |
| `v0.59.1` | 2026-04-11 | Medium | # Fixed - Fix #191, 0.59.0 introduced a regression when the json was preceded by text with parentheses  # Think about sponsoring this library!  This library is free for everyone and it's maintained and developed as a side project so, if you find this library useful for your work, consider offering me a beer via this link: https://github.com/sponsors/mangiucugna |

## Citation

- HTML: https://www.freshcrate.ai/projects/json-repair
- Markdown: https://www.freshcrate.ai/projects/json-repair.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/json-repair/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._