{"id":2263,"library":"rlp","title":"RLP (Recursive Length Prefix)","description":"RLP (Recursive Length Prefix) is a serialization format used extensively in Ethereum to encode arbitrarily nested arrays of binary data. The `rlp` Python library provides efficient functions for encoding Python objects (byte strings, integers, lists/tuples of these) into RLP byte strings and decoding them back. It is actively maintained by the Ethereum project. The current version is 4.1.0.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/ethereum/pyrlp","tags":["encoding","ethereum","serialization","bytes","blockchain"],"install":[{"cmd":"pip install rlp","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"Python","optional":false}],"imports":[{"note":"The `encode` function is directly available at the top-level `rlp` module.","wrong":"import rlp.encode","symbol":"encode","correct":"from rlp import encode"},{"note":"The `decode` function is directly available at the top-level `rlp` module.","wrong":"import rlp.decode","symbol":"decode","correct":"from rlp import decode"},{"note":"While `Serializable` is part of the 'sedes' (serialization/deserialization) module internally, it is exposed directly from the top-level `rlp` package for convenience.","wrong":"from rlp.sedes import Serializable","symbol":"Serializable","correct":"from rlp import Serializable"}],"quickstart":{"code":"import rlp\n\n# Encode a simple byte string\nencoded_string = rlp.encode(b'ethereum')\nprint(f\"Encoded 'ethereum': {encoded_string}\")\n\n# Decode it back\ndecoded_string = rlp.decode(encoded_string)\nprint(f\"Decoded back: {decoded_string}\")\n\n# Encode a list of byte strings and integers\ndata = [b'dog', b'cat', b'elephant', 0, 15, 12345]\nencoded_list = rlp.encode(data)\nprint(f\"\\nEncoded list: {encoded_list}\")\n\n# Decode the list\ndecoded_list = rlp.decode(encoded_list)\nprint(f\"Decoded list: {decoded_list}\")\n\n# Encoding nested lists\nnested_data = [b'a', [b'b', b'c'], [b'd', [b'e', b'f']]]\nencoded_nested = rlp.encode(nested_data)\nprint(f\"\\nEncoded nested: {encoded_nested}\")\n\ndecoded_nested = rlp.decode(encoded_nested)\nprint(f\"Decoded nested: {decoded_nested}\")","lang":"python","description":"This quickstart demonstrates basic RLP encoding and decoding of byte strings, integers, and nested lists. It highlights how the library handles different data types automatically. Note that all string inputs must be byte strings (`b'...'`)."},"warnings":[{"fix":"Ensure your code expects `bytes` objects for string-like data after decoding. Use `decoded_item.decode('utf-8')` if you need a Python `str`.","message":"The output of `rlp.decode` now *always* returns bytes for byte-string elements (or integers for encoded numbers). In versions prior to 3.0.0, it might have returned `str` on Python 2 or behaved inconsistently regarding string types. This change enforces consistency with Python 3 byte strings.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Always convert `str` to `bytes` using `my_string.encode('utf-8')` (or another appropriate encoding) before passing to `rlp.encode`.","message":"When encoding, all string-like elements within lists or directly passed to `rlp.encode` must be byte strings (`bytes`). Passing a Python `str` (e.g., `'hello'`) will result in a `TypeError`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Understand RLP's type differentiation. If you intend to encode a number, pass an `int`. If you intend to encode raw bytes, pass `bytes`.","message":"Be aware of the difference between encoding an integer and encoding a byte string representation of that integer. `rlp.encode(1)` results in `b'\\x01'` (RLP for integer 1). `rlp.encode(b'\\x01')` results in `b'\\x81\\x01'` (RLP for a byte string of length 1, whose value is `b'\\x01'`). Decoding these yields `1` and `b'\\x01'` respectively.","severity":"gotcha","affected_versions":"All"},{"fix":"Explicitly use `[]` for an empty list and `b''` for an empty byte string to ensure the correct RLP encoding is generated.","message":"The RLP encodings for an empty list and an empty byte string are distinct. `rlp.encode([])` results in `b'\\xc0'`. `rlp.encode(b'')` results in `b'\\x80'`. They will decode back to `[]` and `b''` respectively. Confusing these can lead to incorrect data interpretation.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}