Install & Compatibility
Where this runs
tested against v3.4.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decode_car
✓ from libipld import decode_car
✗ from libipld import CID
decode_cid
✓ from libipld import decode_cid
encode_dag_cbor
✓ from libipld import encode_dag_cbor
This quickstart demonstrates encoding a Python dictionary into DAG-CBOR format, decoding it back, and generating a Content Identifier (CID) from the encoded data. This showcases core `libipld` functionality for structured data serialization and content addressing.
from libipld import encode_dag_cbor, decode_dag_cbor, CID
data = {
'name': 'IPLD Example',
'version': 1,
'active': True,
'items': [
{'id': 1, 'value': 'A'},
{'id': 2, 'value': 'B'}
]
}
# Encode Python dict to DAG-CBOR bytes
encoded_bytes = encode_dag_cbor(data)
print(f"Encoded DAG-CBOR (first 20 bytes): {encoded_bytes[:20]}...")
# Decode DAG-CBOR bytes back to Python dict
decoded_data = decode_dag_cbor(encoded_bytes)
print(f"Decoded data: {decoded_data}")
# Create a CID from the encoded bytes (defaults to DAG-CBOR codec, sha2-256 multihash)
content_id = CID.from_bytes(encoded_bytes)
print(f"Generated CID: {content_id}")
print(f"CID version: {content_id.version}")
print(f"CID codec: {content_id.codec}")
print(f"CID multihash: {content_id.multihash.name}")
Debug
Known issues
breakingIn v2.0.0 and subsequent versions, CIDs in CAR block keys and DAG-CBOR changed from string representation to raw byte representation. This significantly affects how CIDs are handled when interfacing with CAR files or DAG-CBOR directly.fixEnsure your code expects and provides `bytes` objects for CIDs, particularly when using `decode_car`, `encode_dag_cbor`, or `CID.from_bytes()`. If migrating from older `libipld` versions, update all CID parsing and serialization logic.
affects: >=2.0.0
breakingPython 3.7 support was officially dropped in `libipld` v3.0.0. Projects still using Python 3.7 will need to upgrade their Python environment to at least 3.8 to use v3.0.0 or newer.fixUpgrade your Python environment to 3.8 or newer. The library currently supports CPython 3.8 to 3.14.
affects: >=3.0.0
breaking`libipld` dropped support for PyPy 3.8 in v3.0.1, and PyPy 3.9/3.10 in v3.2.0, aligning with their upstream end-of-life status. PyPy 3.11+ is currently supported.fixIf using PyPy, ensure you are on PyPy 3.11 or a newer supported version. For CPython, versions 3.8-3.14 are supported.
affects: >=3.0.1 for PyPy 3.8; >=3.2.0 for PyPy 3.9/3.10
gotchaEarlier versions of `libipld` (before v3.3.0 and v1.2.3) had significantly slower performance for CAR and DAG-CBOR decoding/encoding. Users on older versions might experience substantial performance bottlenecks.fixUpgrade to the latest version of `libipld` (v3.3.0+) to benefit from major performance optimizations for CAR and DAG-CBOR operations, which can be up to 2x faster in some cases.
affects: <3.3.0
Upgrade
Version history
3.4.1latest on PyPI · released May 27, 2026
Audit
Dependencies
No dependency data recorded yet.