{"id":9198,"library":"py-cid","title":"py-cid: Self-describing content-addressed identifiers","description":"py-cid is a Python library that provides an implementation of the Content Identifier (CID) specification. CIDs are self-describing content-addressed identifiers used in distributed systems like IPFS and IPLD, leveraging cryptographic hashing and multiformats for flexible self-description. The library is actively maintained, with version 0.5.0 being the latest release, supporting Python 3.10 and newer.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/ipld/py-cid","tags":["cid","ipfs","ipld","cryptography","content-addressing","multiformats"],"install":[{"cmd":"pip install py-cid","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Used for cryptographic hashing within CIDs.","package":"py-multihash","optional":false},{"reason":"Required to handle different content types (codecs) within CIDs, especially for CIDv1.","package":"py-multicodec","optional":false},{"reason":"Needed for encoding/decoding CIDv1 strings into various multibase formats.","package":"py-multibase","optional":false}],"imports":[{"symbol":"make_cid","correct":"from cid import make_cid"},{"symbol":"CIDv0","correct":"from cid import CIDv0"},{"symbol":"CIDv1","correct":"from cid import CIDv1"}],"quickstart":{"code":"from cid import make_cid, CIDv0, CIDv1\n\n# Create a CIDv0 from a base58-encoded multihash\ncid_v0_str = 'QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpu5rmrkPdT3L4'\ncid0 = make_cid(cid_v0_str)\nprint(f\"CIDv0: {cid0}\")\nprint(f\"Version: {cid0.version}, Codec: {cid0.codec}, Multihash: {cid0.multihash.hex()}\")\n\n# Create a CIDv1 from a multibase-encoded CID string\ncid_v1_str = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3fzmsyqhwfsgr2zfdnc2dsxze'\ncid1 = make_cid(cid_v1_str)\nprint(f\"CIDv1: {cid1}\")\nprint(f\"Version: {cid1.version}, Codec: {cid1.codec}, Multihash: {cid1.multihash.hex()}\")\n\n# Accessing components\nprint(f\"CIDv0 string: {str(cid0)}\")\nprint(f\"CIDv1 encoded in base32: {cid1.encode('base32')}\") # requires py-multibase","lang":"python","description":"This quickstart demonstrates how to create CIDv0 and CIDv1 objects using `make_cid` from both base58 and multibase encoded strings. It also shows how to access their version, codec, multihash, and how to encode CIDv1 into different multibase formats."},"warnings":[{"fix":"Ensure you are installing `py-cid` from the `ipld/py-cid` project and using `pip install py-cid` for the current API. Avoid `py-multiformats-cid` if you intend to use the latest `py-cid` features.","message":"The PyPI package `py-cid` was previously renamed to `py-multiformats-cid` around version 0.4.0 (2022-10-31). The current `py-cid` (version 0.5.0+) is a distinct project. Installing `py-multiformats-cid` will provide an older, incompatible API if you are expecting the current `py-cid` behavior.","severity":"breaking","affected_versions":"<=0.4.0 (for the old project that was renamed)"},{"fix":"Be explicit about the CID version you expect. Use `make_cid` which handles both, or `CIDv0` and `CIDv1` constructors directly for specific versions. Remember `cid.encode()` on `CIDv0` will only produce Base58, while `CIDv1.encode(base)` allows various multibase encodings.","message":"CIDv0 and CIDv1 have fundamental differences in structure and string representation. CIDv0 CIDs are always Base58-encoded and use the `dag-pb` codec implicitly. CIDv1 CIDs are multibase-encoded (e.g., base32, base64) and explicitly include a codec prefix. Mixing up expectations can lead to incorrect CID parsing or encoding errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using `pip install py-cid`.","cause":"The `py-cid` library is not installed or the environment is incorrect.","error":"ModuleNotFoundError: No module named 'cid'"},{"fix":"`make_cid` generally infers the CID version and codec from the provided string. For `CIDv1` with a raw multihash, use `CIDv1('codec-name', multihash_bytes)` directly. For example: `CIDv1('raw', b'\\x12\\x20' + b'hash_bytes')`.","cause":"You are likely attempting to pass a 'codec' argument to `make_cid` when it expects to infer it from the input string, or are misusing the `CIDv1` constructor.","error":"TypeError: make_cid() takes 1 positional argument but 2 were given"},{"fix":"Ensure you are working with a `CIDv1` object if you need flexible multibase encoding. For `CIDv0`, use `str(cid_obj)` or `cid_obj.encode()` to get its Base58 string representation.","cause":"You are trying to call a multibase encoding method on a CIDv0 object. CIDv0 only supports Base58 encoding.","error":"AttributeError: 'CIDv0' object has no attribute 'encode_multibase'"}]}