{"id":841,"library":"cbor2","title":"CBOR (de)serializer with extensive tag support","description":"cbor2 is a Python library for encoding and decoding Concise Binary Object Representation (CBOR) data, fully compatible with RFC 8949. It offers a simple API similar to the `json` or `pickle` modules, with extensive support for CBOR tags and standard library objects. Currently at version 5.9.0, it is actively maintained with a regular release cadence, featuring a highly performant Rust-based backend for improved memory safety and performance.","status":"active","version":"5.9.0","language":"python","source_language":"en","source_url":"https://github.com/agronholm/cbor2","tags":["serialization","cbor","binary","data format"],"install":[{"cmd":"pip install cbor2","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"dumps","correct":"from cbor2 import dumps"},{"symbol":"loads","correct":"from cbor2 import loads"},{"symbol":"dump","correct":"from cbor2 import dump"},{"symbol":"load","correct":"from cbor2 import load"},{"note":"The `cbor2.encoder` module was deprecated in 5.5.0 and will be removed in the next major release (6.x.x). Import directly from `cbor2` instead.","wrong":"from cbor2.encoder import CBOREncoder","symbol":"CBOREncoder","correct":"from cbor2 import CBOREncoder"},{"note":"The `cbor2.decoder` module was deprecated in 5.5.0 and will be removed in the next major release (6.x.x). Import directly from `cbor2` instead.","wrong":"from cbor2.decoder import CBORDecoder","symbol":"CBORDecoder","correct":"from cbor2 import CBORDecoder"}],"quickstart":{"code":"import cbor2\n\ndata_to_encode = {'name': 'Alice', 'age': 30, 'is_active': True}\n\n# Encode Python object to CBOR bytestring\nencoded_data = cbor2.dumps(data_to_encode)\nprint(f\"Encoded CBOR: {encoded_data}\")\n\n# Decode CBOR bytestring back to Python object\ndecoded_data = cbor2.loads(encoded_data)\nprint(f\"Decoded Python object: {decoded_data}\")\n\n# Example with file-like objects\n# import io\n# output_buffer = io.BytesIO()\n# cbor2.dump(data_to_encode, output_buffer)\n# output_buffer.seek(0)\n# decoded_from_file = cbor2.load(output_buffer)\n# print(f\"Decoded from file-like object: {decoded_from_file}\")","lang":"python","description":"This quickstart demonstrates the basic encoding and decoding of Python objects to and from CBOR bytestrings using `cbor2.dumps()` and `cbor2.loads()`."},"warnings":[{"fix":"Update imports to load symbols directly from the `cbor2` package (e.g., `from cbor2 import dumps` instead of `from cbor2.encoder import dumps`).","message":"The modules `cbor2.encoder`, `cbor2.decoder`, and `cbor2.types` have been deprecated since version 5.5.0 and will be removed in the upcoming 6.x.x major release. Direct imports from these modules will cause `ModuleNotFoundError`.","severity":"breaking","affected_versions":">=5.5.0 (deprecation), upcoming 6.x.x (removal)"},{"fix":"Review the official `cbor2` documentation for version 6.0.0 for a complete list of breaking changes and adapt custom `tag_hook` and `object_hook` implementations. Avoid direct calls to previously available individual decoding functions.","message":"Version 6.0.0 (currently in release candidate) introduces several backward-incompatible changes, including signature changes for `tag_hook` and `object_hook` decoder callables, removal of `break_marker`, changes in IP address encoding tags, and removal of individual decoding functions from the API.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"To encode cyclic data structures, enable value sharing by passing `value_sharing=True` to `cbor2.dumps()` or `cbor2.dump()`. Be aware that support for value sharing may be rare in other CBOR implementations.","message":"When encoding Python objects with cyclic references (e.g., lists or dictionaries that refer back to themselves), `cbor2` will raise a `CBOREncodeError` by default. CBOR supports shared value references as an extension.","severity":"gotcha","affected_versions":"all"},{"fix":"Always ensure the encoder or writer is properly closed, either explicitly with `writer.close()` or by using a `with` statement.","message":"When using `CBOREncoder` or `CBORWriter` for streaming (e.g., writing to a file), forgetting to call `close()` can result in truncated or incomplete CBOR data. The `with` statement handles this automatically.","severity":"gotcha","affected_versions":"all"},{"fix":"Wrap deserialization calls in a `try-except cbor2.CBORDecodeError` block to gracefully handle potential decoding issues and ensure application stability.","message":"Decoding malformed or corrupted CBOR data with `cbor2.loads()` or `cbor2.load()` will raise a `cbor2.CBORDecodeError`, potentially crashing the application if not handled.","severity":"gotcha","affected_versions":"all"},{"fix":"Always verify the type of decoded data, especially when dealing with potentially tagged values, and be prepared to handle the appropriate Python object types that `cbor2` maps to standard CBOR tags.","message":"When decoding CBOR, a value that appears simple (like a string or integer) might actually be a CBOR-tagged type (e.g., a `datetime` object for a timestamp tag). If your code expects a specific simple Python type, this can lead to runtime errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T20:18:03.539Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the cbor2 package using pip: `pip install cbor2`.","cause":"The cbor2 library is not installed in your current Python environment or is not accessible within your Python path.","error":"ModuleNotFoundError: No module named 'cbor2'"},{"fix":"Ensure the input data is a complete and correctly formatted CBOR byte string. Wrap decoding calls in a `try-except cbor2.CBORDecodeError` block to gracefully handle invalid input.","cause":"The input byte string provided to cbor2.loads() or cbor2.load() is not valid CBOR data, is corrupted, or is prematurely truncated, leading the decoder to fail when trying to read the next data item.","error":"cbor2.CBORDecodeError: error reading major type at index X: index out of range"},{"fix":"Provide a custom encoder function by registering it with the `encoders` argument or by using the `default` argument in `cbor2.dumps()` or `cbor2.dump()` to specify how to handle the unsupported type.","cause":"You are attempting to serialize a Python object type (e.g., a custom class instance or certain standard library types) for which cbor2 does not have a default encoding mechanism.","error":"cbor2.CBOREncodeTypeError: type X is not cbor2 encodable"},{"fix":"Enable value sharing during encoding by passing `value_sharing=True` to `cbor2.dumps()` or `cbor2.dump()`. For custom types, you may also need to decorate custom encoder and decoder callbacks with `@shareable_encoder` and `@shareable_decoder`.","cause":"The Python object you are trying to encode contains circular references (e.g., an object directly or indirectly references itself), and cbor2's value sharing feature is not enabled to handle such structures.","error":"cbor2.CBOREncodeValueError: cyclic data structure detected"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"6.0.1","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"19.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.2,"disk_size":"18.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0,"mem_mb":0.5,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.2,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"20.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.01,"mem_mb":0.7,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.5,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"12.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.1,"disk_size":"12.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.1,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.7,"disk_size":"12.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"12.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.1,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.3,"disk_size":"18.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.3,"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}]}}