Typing Stubs for ujson

5.10.0.20250822 · maintenance · verified Fri Apr 10

This package provides static typing stubs for the `ujson` library, enabling type checkers like MyPy and Pyright to analyze code that uses `ujson`. The current version is 5.10.0.20250822. These stubs are sourced from the typeshed project. Note that `ujson` versions 5.11.0 and newer include their own type annotations, making `types-ujson` primarily relevant for older `ujson` versions or specific development environments.

Warnings

deprecated The underlying `ujson` library is in maintenance-only mode due to architectural limitations and potential security vulnerabilities, with active development paused. Users are encouraged to consider `orjson` as a faster and more secure alternative.
Fix: Evaluate migrating from `ujson` to `orjson` or the standard `json` library, especially for new projects or performance-critical applications.
breaking For `ujson` versions 5.11.0 and newer, the `ujson` package itself includes type annotations. Installing `types-ujson` alongside these versions is redundant and may lead to conflicts or incorrect type checking behavior.
Fix: If using `ujson` 5.11.0 or newer, uninstall `types-ujson` (`pip uninstall types-ujson`). Rely on the type annotations provided directly by the `ujson` package.
gotcha `types-ujson` only provides type hints; the actual `ujson` library must be installed for runtime execution. Failing to install `ujson` will result in `ModuleNotFoundError` at runtime.
Fix: Ensure both `ujson` and `types-ujson` are installed via `pip install ujson types-ujson`.
gotcha `ujson.dumps()` has known issues with floating-point precision, which can lead to slight discrepancies compared to the standard library's `json.dumps()`, even when `double_precision` is explicitly set.
Fix: If exact floating-point precision is critical, consider using Python's standard `json` module or ensure thorough testing of `ujson`'s output for your specific data.
gotcha `ujson` has experienced memory leak issues, particularly in `ujson.dumps()` when repeatedly encoding large objects or dictionaries with non-string keys within a loop.
Fix: Ensure `ujson` is updated to at least version `5.12.0` to address known vulnerabilities and memory-related bugs. Optimize code to avoid repeated encoding of large, mutable objects in performance-critical loops if memory consumption becomes an issue.
gotcha Several security vulnerabilities have been identified in `ujson`, including integer overflows with the `indent` parameter and improper handling of syntactically invalid JSON structures.
Fix: Upgrade `ujson` to version 5.12.0 or higher to mitigate these known security risks.

Install

pip install ujson types-ujson Install `ujson` and its typing stubs

Imports

ujson
```
import ujson
```
dumps
```
from ujson import dumps
```
loads
```
from ujson import loads
```

Quickstart

This quickstart demonstrates basic usage of `ujson.dumps` and `ujson.loads` with type hints, leveraging the `types-ujson` stubs for static analysis.

import ujson
from typing import Dict, Any, List

data: Dict[str, Any] = {
    "name": "Alice",
    "age": 30,
    "isStudent": False,
    "courses": ["History", "Math"]
}

# Encode Python dict to JSON string with type hinting
json_string: str = ujson.dumps(data)
print(f"Encoded JSON: {json_string}")

# Decode JSON string to Python dict with type hinting
decoded_data: Dict[str, Any] = ujson.loads(json_string)
print(f"Decoded data: {decoded_data}")

# Accessing a value from decoded data
name: str = decoded_data['name']
print(f"Name: {name}")

view raw JSON →