Install & Compatibility
Where this runs
tested against v3.6.2 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.048s · 18.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.042s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
orjson
✓ import orjson
✗ from types_orjson import ...
You do not directly import from `types_orjson`. Install the package, and type checkers will automatically find its stubs when you import `orjson`.
This quickstart demonstrates how to use `orjson` with `types-orjson` installed. Type checkers will now understand the types returned by `orjson.loads` and expected by `orjson.dumps`, ensuring type safety in your code without needing direct `types-orjson` imports.
import orjson
from typing import Any, Dict
def process_data(data_str: str) -> Dict[str, Any]:
# orjson.loads provides type hints thanks to types-orjson
parsed_data: Dict[str, Any] = orjson.loads(data_str)
# orjson.dumps provides type hints
re_serialized_data: bytes = orjson.dumps(parsed_data, option=orjson.OPT_INDENT_2)
print(re_serialized_data.decode())
return parsed_data
if __name__ == '__main__':
json_string = '{"name": "Alice", "age": 30, "city": "New York"}'
result = process_data(json_string)
print(f"Parsed data: {result}")
# To verify types, run a type checker:
# mypy your_script_name.py
# or pyright your_script_name.py
Debug
Known issues
gotchaInstalling `types-orjson` alone is not enough. You must also install the actual `orjson` library for your code to run at runtime. `types-orjson` only provides type hints for `orjson`.fixEnsure both `pip install orjson` and `pip install types-orjson` are executed.
affects: All
gotcha`types-orjson` provides static type information for type checkers (e.g., MyPy, Pyright) only. It does not add any runtime functionality or change the behavior of `orjson` itself. Your code will function identically at runtime with or without `types-orjson` installed.fixUnderstand that stubs are for development-time type validation, not runtime execution. Do not attempt to import from `types_orjson`.
affects: All
breakingWhile `typeshed` strives to keep stubs up-to-date, significant API changes in `orjson` itself might lead to temporary inconsistencies or outdated type hints in `types-orjson` until the stubs are updated. This typically means your type checker might report errors even if the runtime code is correct for a new `orjson` version.fixIf facing type checking errors after updating `orjson`, check the `typeshed` GitHub for relevant issues or pull requests, or temporarily pin `orjson` to an older version compatible with the stubs.
affects: Dependent on `orjson` major releases
Upgrade
Version history
3.6.2latest on PyPI · released Jan 7, 2022
Audit
Dependencies
orjsonrequiredProvides type stubs for this library; `orjson` itself must be installed for runtime functionality.