Install & Compatibility
Where this runs
tested against v1.23 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.016s · 26.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.016s · 25MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rapidjson
✓ import rapidjson
dumps
✓ rapidjson.dumps(data)
✗ json.dumps(data)
While API-compatible, directly using `rapidjson.dumps` is intended. Be aware of minor incompatibilities with the standard `json` module's behavior.
loads
✓ rapidjson.loads(json_string)
✗ json.loads(json_string)
While API-compatible, directly using `rapidjson.loads` is intended. Be aware of minor incompatibilities with the standard `json` module's behavior, especially regarding UTF-8 enforcement for bytes.
Decoder
✓ from rapidjson import Decoder, PM_COMMENTS, PM_TRAILING_COMMAS
Encoder
✓ from rapidjson import Encoder
This quickstart demonstrates the basic serialization (`dumps`) and deserialization (`loads`) functionality of `python-rapidjson`, which mirrors the standard library `json` module. It also includes an example of using the `Decoder` class with `parse_mode` flags to handle more relaxed JSON syntax, such as comments and trailing commas.
import rapidjson
import os
# Example data
data = {'name': 'Alice', 'age': 30, 'isStudent': False}
# Serialize to JSON string
json_string = rapidjson.dumps(data)
print(f"Serialized: {json_string}")
# Deserialize from JSON string
loaded_data = rapidjson.loads(json_string)
print(f"Deserialized: {loaded_data}")
# Example with custom Decoder for relaxed syntax (JSONC, trailing commas)
try:
from rapidjson import Decoder, PM_COMMENTS, PM_TRAILING_COMMAS
decoder = Decoder(parse_mode=PM_COMMENTS | PM_TRAILING_COMMAS)
relaxed_json = '''
{
"item": "value", /* This is a comment */
"count": 123, // Another comment
"enabled": true, // Trailing comma
}
'''
parsed_relaxed = decoder(relaxed_json)
print(f"Parsed relaxed JSON: {parsed_relaxed}")
except ImportError:
print("Custom Decoder features not available (might be an older version or specific flags are missing).")
Debug
Known issues
gotchaAPI Incompatibilities with standard `json` module: While `python-rapidjson` aims for `json` module compatibility, there are notable differences. `json.loads()` for bytes input only supports UTF-8. Dictionary key coercion (e.g., `True` to 'true') is not performed by default. The `indent` argument for pretty printing is supported, but specific `json` module behaviors like `None` for no indent or `sort_keys` as a direct argument have been superseded by `mapping_mode` options in v1.0+ (though old arguments are kept for backward compatibility).fixConsult the `python-rapidjson` documentation for `Incompatibilities` and `Exposed functions and symbols` sections. Use specific `datetime_mode`, `number_mode`, `parse_mode`, `write_mode`, `iterable_mode`, and `mapping_mode` flags for fine-grained control.
affects: All versions, v1.0+ for `mapping_mode` changes
gotchaC++ Compiler Requirement for Source Installation: If a pre-compiled binary wheel is not available for your specific Python version and operating system, `pip install` will attempt to compile `python-rapidjson` from source. This requires a C++ compiler toolchain (e.g., build-essential on Linux, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows) to be installed on your system.fixEnsure you have a C++ compiler installed, or install `python-rapidjson` via `conda` which typically manages compiler dependencies.
affects: All versions
gotcha`DM_UNIX_TIME` for `dumps` (Serialization) Only: The `DM_UNIX_TIME` option, used with `datetime_mode` for serializing `date`, `datetime`, and `time` objects as numeric timestamps, is an irreversible operation. Consequently, it is only supported for `dumps()` (serialization) functions. Passing `DM_UNIX_TIME` to `loads()` (deserialization) will raise an error.fixDo not use `DM_UNIX_TIME` when calling `rapidjson.loads()` or initializing a `Decoder`. Select an appropriate `datetime_mode` that supports both serialization and deserialization if round-tripping datetime objects is required (e.g., `DM_ISO8601`).
affects: All versions
gotchaRecursion Limit for Parsing: As of version 1.15, `python-rapidjson` honors the Python recursion limit during parsing to prevent potential denial-of-service attacks related to extremely deeply nested JSON structures. Prior versions may not have enforced this limit, making them potentially vulnerable to stack overflow issues with malicious inputs.fixUpgrade to version 1.15 or newer. For applications processing untrusted or extremely deep JSON, be aware of `sys.setrecursionlimit()` and how it affects parsing.
affects: Versions < 1.15 (potential vulnerability), all versions (behavior change)
Upgrade
Version history
1.23latest on PyPI · released Dec 7, 2025
Audit
Dependencies
RapidJSONrequiredCore C++ library wrapped by python-rapidjson. Included as a submodule, but requires a C++ compiler if binary wheels are unavailable.