libipld

3.3.2 · active · verified Mon Apr 13

libipld provides Python bindings to a high-performance Rust IPLD library, enabling fast encoding and decoding of IPLD data structures such as DAG-CBOR, CAR files, and CIDs. It's built for efficiency, often used in decentralized web and blockchain applications. The current version is 3.3.2, with active development and frequent minor releases addressing performance and bug fixes.

Warnings

breaking In 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.
Fix: Ensure 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.
breaking Python 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.
Fix: Upgrade your Python environment to 3.8 or newer. The library currently supports CPython 3.8 to 3.14.
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.
Fix: If using PyPy, ensure you are on PyPy 3.11 or a newer supported version. For CPython, versions 3.8-3.14 are supported.
gotcha Earlier 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.
Fix: Upgrade 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.

Install

pip install libipld Install stable version

Imports

CID
```
from libipld import CID
```
encode_dag_cbor
```
from libipld import encode_dag_cbor
```
decode_dag_cbor
```
from libipld import decode_dag_cbor
```
decode_car
```
from libipld import decode_car
```

Quickstart

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}")

view raw JSON →