{"id":6931,"library":"types-orjson","title":"Typing Stubs for orjson","description":"types-orjson provides type hints (typing stubs) for the high-performance `orjson` JSON library. It is part of the Python `typeshed` project, which maintains type stubs for various third-party packages. These stubs enable static type checkers like MyPy or Pyright to validate `orjson`'s API usage, enhancing code reliability and developer experience. The current version is 3.6.2, and updates are typically released in sync with `typeshed`'s update cycle or when `orjson` has significant API changes.","status":"active","version":"3.6.2","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","orjson","typeshed"],"install":[{"cmd":"pip install types-orjson orjson","lang":"bash","label":"Install stubs and orjson"}],"dependencies":[{"reason":"Provides type stubs for this library; `orjson` itself must be installed for runtime functionality.","package":"orjson","optional":false}],"imports":[{"note":"You do not directly import from `types_orjson`. Install the package, and type checkers will automatically find its stubs when you import `orjson`.","wrong":"from types_orjson import ...","symbol":"orjson","correct":"import orjson"}],"quickstart":{"code":"import orjson\nfrom typing import Any, Dict\n\ndef process_data(data_str: str) -> Dict[str, Any]:\n    # orjson.loads provides type hints thanks to types-orjson\n    parsed_data: Dict[str, Any] = orjson.loads(data_str)\n    \n    # orjson.dumps provides type hints\n    re_serialized_data: bytes = orjson.dumps(parsed_data, option=orjson.OPT_INDENT_2)\n    print(re_serialized_data.decode())\n    return parsed_data\n\nif __name__ == '__main__':\n    json_string = '{\"name\": \"Alice\", \"age\": 30, \"city\": \"New York\"}'\n    result = process_data(json_string)\n    print(f\"Parsed data: {result}\")\n    # To verify types, run a type checker:\n    # mypy your_script_name.py\n    # or pyright your_script_name.py","lang":"python","description":"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."},"warnings":[{"fix":"Ensure both `pip install orjson` and `pip install types-orjson` are executed.","message":"Installing `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`.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand that stubs are for development-time type validation, not runtime execution. Do not attempt to import from `types_orjson`.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"fix":"If 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.","message":"While `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.","severity":"breaking","affected_versions":"Dependent on `orjson` major releases"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}