{"id":996,"library":"mashumaro","title":"mashumaro","description":"mashumaro is a fast and well-tested serialization library built on top of Python dataclasses. It provides efficient conversion of dataclass instances to and from various formats like JSON, YAML, TOML, MessagePack, and plain dictionaries. It is actively maintained with frequent releases, currently at version 3.20.","status":"active","version":"3.20","language":"python","source_language":"en","source_url":"https://github.com/Fatal1ty/mashumaro","tags":["serialization","deserialization","dataclasses","json","yaml","toml","msgpack"],"install":[{"cmd":"pip install mashumaro","lang":"bash","label":"Default Install"},{"cmd":"pip install mashumaro[orjson]","lang":"bash","label":"Install with orjson for faster JSON"}],"dependencies":[{"reason":"Optional dependency for faster JSON serialization/deserialization.","package":"orjson","optional":true}],"imports":[{"note":"Primary mixin for JSON serialization/deserialization with dataclasses.","symbol":"DataClassJSONMixin","correct":"from mashumaro.mixins.json import DataClassJSONMixin"},{"note":"Core mixin for dictionary serialization/deserialization with dataclasses.","symbol":"DataClassDictMixin","correct":"from mashumaro import DataClassDictMixin"},{"note":"For generating JSON Schema from dataclasses.","symbol":"build_json_schema","correct":"from mashumaro.jsonschema import build_json_schema"}],"quickstart":{"code":"from dataclasses import dataclass\nfrom mashumaro.mixins.json import DataClassJSONMixin\n\n@dataclass\nclass User(DataClassJSONMixin):\n    name: str\n    email: str\n    age: int\n\n# Serialize to JSON\nuser = User(name='Alice', email='alice@example.com', age=30)\njson_str = user.to_json()\nprint(f\"Serialized: {json_str}\")\n\n# Deserialize from JSON\nrestored_user = User.from_json(json_str)\nprint(f\"Deserialized: {restored_user}\")\nassert restored_user == user","lang":"python","description":"Define a dataclass inheriting from `DataClassJSONMixin` to automatically gain `to_json()` and `from_json()` methods for seamless JSON serialization and deserialization."},"warnings":[{"fix":"Review deserialization logic for fields using `Union` or basic types to align with the new, more precise behavior. Explicitly define serialization/deserialization strategies if specific coercions are required.","message":"In v3.15, deserialization behavior for Unions with `int | float`, `str`, `bool`, and `NoneType` changed. Values are now passed through without coercion for numeric types (if they match), `str` is guaranteed a string version, `bool` uses standard truth testing, and `NoneType` is guaranteed `None`. This can lead to different deserialization results if your application relied on previous implicit coercions or conversions.","severity":"breaking","affected_versions":">=3.15"},{"fix":"Upgrade Python to 3.9 or higher, or pin `mashumaro<3.15` in your project dependencies.","message":"Support for Python 3.8 was dropped in mashumaro v3.15. Projects using Python 3.8 must pin mashumaro to a version prior to 3.15.","severity":"breaking","affected_versions":">=3.15"},{"fix":"Upgrade to mashumaro v3.13.1 or later to get correct type annotations for `DataClassORJSONMixin.to_json`. Consider using `to_jsonb()` if byte output is desired for performance.","message":"When using `DataClassORJSONMixin`, prior to v3.13.1, the `to_json` method's type annotation incorrectly returned `str`. This was fixed in v3.13.1 to return `str` or `bytes` correctly depending on `orjson_options`, affecting static analysis and potentially runtime if strict type checks are in place.","severity":"gotcha","affected_versions":"<3.13.1"},{"fix":"Use Mixins when your root data structure is a dataclass. Use Codecs when you need to serialize/deserialize arbitrary types (like a `List[datetime]`) or top-level collections that are not directly represented by a single dataclass.","message":"Mashumaro offers two primary approaches for serialization: Mixins (e.g., `DataClassJSONMixin`) for dataclass models, and Codecs (e.g., `JSONDecoder`, `JSONEncoder`) for converting arbitrary Python types or top-level collections. Choosing the wrong approach can lead to more verbose code or lack of desired functionality.","severity":"gotcha","affected_versions":"All"},{"fix":"Be explicit with `forbid_extra_keys` in your `Config` if you want strict validation. If using `Alias(...)` for field aliasing and require deserialization by both alias and original field name, set `allow_deserialization_not_by_alias=True` in your dataclass `Config`.","message":"The `forbid_extra_keys` configuration option (introduced in v3.13) and `Alias(...)` annotation for field aliasing (also v3.13) offer powerful control but can lead to deserialization failures if not configured correctly. Extra keys will be rejected if `forbid_extra_keys` is set to `True`, and fields might not deserialize by their original name if `Alias` is used without `allow_deserialization_not_by_alias`.","severity":"gotcha","affected_versions":">=3.13"}],"env_vars":null,"last_verified":"2026-05-12T22:27:37.111Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure that the input data for deserialization contains all non-optional fields required by the dataclass. For example, if 'name: str' is a field, the input dictionary must have a 'name' key.","cause":"This error occurs during deserialization when the input data (e.g., a dictionary or JSON string) lacks a required field defined in the target dataclass.","error":"mashumaro.exceptions.MissingField: Field \"<field_name>\" of type <field_type> is missing in <dataclass_name> instance"},{"fix":"Either ensure the input dictionary only contains keys corresponding to dataclass fields, or set `forbid_extra_keys = False` in your dataclass's `Config` or `code_generation_options` during deserialization if you want to ignore extra keys.","cause":"This error happens during deserialization if the input dictionary contains keys that are not defined as fields in the dataclass, and the `forbid_extra_keys` configuration option is enabled.","error":"mashumaro.exceptions.ExtraKeysError: Serialized dict has keys that are not defined in <dataclass_name>: <extra_keys_str>"},{"fix":"Define a custom serialization strategy for the field's type using `mashumaro.types.SerializationStrategy` or `mashumaro.types.SerializableType`, or ensure the field's type is one of Mashumaro's natively supported types or a dataclass itself.","cause":"This error indicates that Mashumaro does not know how to serialize or deserialize the type of a specific field within your dataclass.","error":"mashumaro.exceptions.UnserializableField: Field \"<field_name>\" of type <field_type> in <dataclass_name> is not serializable"},{"fix":"Install the required optional dependency using pip, often with Mashumaro's extras, like `pip install mashumaro[orjson]` for ORJSON support or `pip install mashumaro[yaml]` for YAML support.","cause":"This error occurs when you attempt to use a Mashumaro mixin or feature that relies on an optional third-party library (e.g., `orjson` for `DataClassORJSONMixin`, `pyyaml` for `DataClassYAMLMixin`) that has not been installed.","error":"mashumaro.exceptions.ThirdPartyModuleNotFoundError: Install \"<module_name>\" to use it as the serialization method for the field \"<field_name>\" in <dataclass_name>"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.21","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"3.20","pypi_latest":"3.21","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.12,"mem_mb":4.2,"disk_size":"18.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":4.2,"disk_size":"18.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.11,"mem_mb":4.2,"disk_size":"19.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":4.2,"disk_size":"19.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.09,"mem_mb":4.2,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":4.2,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.2,"import_time_s":0.09,"mem_mb":4.2,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":4.2,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":4.4,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.4,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":4.4,"disk_size":"21.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.4,"disk_size":"21.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.16,"mem_mb":4.4,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.4,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2,"import_time_s":0.15,"mem_mb":4.4,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.4,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"12.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"12.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.14,"mem_mb":4.3,"disk_size":"13.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"13.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"14M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"12.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"12.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.13,"mem_mb":4.5,"disk_size":"12.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"12.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.11,"mem_mb":4.1,"disk_size":"18.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.1,"disk_size":"18.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.11,"mem_mb":4.1,"disk_size":"18.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.1,"disk_size":"18.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.9,"import_time_s":0.1,"mem_mb":4.1,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"mashumaro","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":4.1,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.5,"import_time_s":0.1,"mem_mb":4.1,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"orjson","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":4.1,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}