CBOR (de)serializer with extensive tag support

5.9.0 verified Tue May 12 auth: no python install: verified

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.

pip install cbor2

Common errors

error ModuleNotFoundError: No module named 'cbor2' ↓

cause The cbor2 library is not installed in your current Python environment or is not accessible within your Python path.

fix

Install the cbor2 package using pip: pip install cbor2.

error cbor2.CBORDecodeError: error reading major type at index X: index out of range ↓

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.

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.

error cbor2.CBOREncodeTypeError: type X is not cbor2 encodable ↓

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.

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.

error cbor2.CBOREncodeValueError: cyclic data structure detected ↓

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.

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.

Warnings

breaking 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`. ↓

fix Update imports to load symbols directly from the `cbor2` package (e.g., `from cbor2 import dumps` instead of `from cbor2.encoder import dumps`).

breaking 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

fix Always ensure the encoder or writer is properly closed, either explicitly with `writer.close()` or by using a `with` statement.

gotcha Decoding malformed or corrupted CBOR data with `cbor2.loads()` or `cbor2.load()` will raise a `cbor2.CBORDecodeError`, potentially crashing the application if not handled. ↓

fix Wrap deserialization calls in a `try-except cbor2.CBORDecodeError` block to gracefully handle potential decoding issues and ensure application stability.

gotcha 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. ↓

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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 19.1M

3.10 alpine (musl) - - 0.02s 18.5M

3.10 slim (glibc) wheel 1.6s 0.00s 20M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.02s 21.0M

3.11 alpine (musl) - - 0.04s 20.4M

3.11 slim (glibc) wheel 1.6s 0.01s 21M

3.11 slim (glibc) - - 0.03s 21M

3.12 alpine (musl) wheel - 0.01s 12.9M

3.12 alpine (musl) - - 0.02s 12.4M

3.12 slim (glibc) wheel 1.5s 0.01s 13M

3.12 slim (glibc) - - 0.02s 13M

3.13 alpine (musl) wheel - 0.01s 12.6M

3.13 alpine (musl) - - 0.02s 12.0M

3.13 slim (glibc) wheel 1.7s 0.01s 13M

3.13 slim (glibc) - - 0.02s 13M

3.9 alpine (musl) wheel - 0.01s 18.0M

3.9 alpine (musl) - - 0.02s 18.0M

3.9 slim (glibc) wheel 1.9s 0.02s 19M

3.9 slim (glibc) - - 0.01s 19M

Imports

dumps
```
from cbor2 import dumps
```
loads
```
from cbor2 import loads
```
dump
```
from cbor2 import dump
```
load
```
from cbor2 import load
```
CBOREncoder
wrong
```
from cbor2.encoder import CBOREncoder
```
correct
```
from cbor2 import CBOREncoder
```
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.
CBORDecoder
wrong
```
from cbor2.decoder import CBORDecoder
```
correct
```
from cbor2 import CBORDecoder
```
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.

Quickstart last tested: 2026-04-24

This quickstart demonstrates the basic encoding and decoding of Python objects to and from CBOR bytestrings using `cbor2.dumps()` and `cbor2.loads()`.

import cbor2

data_to_encode = {'name': 'Alice', 'age': 30, 'is_active': True}

# Encode Python object to CBOR bytestring
encoded_data = cbor2.dumps(data_to_encode)
print(f"Encoded CBOR: {encoded_data}")

# Decode CBOR bytestring back to Python object
decoded_data = cbor2.loads(encoded_data)
print(f"Decoded Python object: {decoded_data}")

# Example with file-like objects
# import io
# output_buffer = io.BytesIO()
# cbor2.dump(data_to_encode, output_buffer)
# output_buffer.seek(0)
# decoded_from_file = cbor2.load(output_buffer)
# print(f"Decoded from file-like object: {decoded_from_file}")