rlp

library5.0.0pypypi✓ verified 26d ago

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.

serialization

pip install rlp

github ↗package ↗

INSTALL

IMPORT

SIG · RLP

rlp

serializationpythonv5.0.0

Install

3.8s avg

Import

663ms

Disk

40MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.0.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.684s · 40.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.642s · 42MB

40MB installed

● package 40MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

encode

✓ from rlp import encode

✗ import rlp.encode

The `encode` function is directly available at the top-level `rlp` module.

decode

✓ from rlp import decode

✗ import rlp.decode

The `decode` function is directly available at the top-level `rlp` module.

Serializable

✓ from rlp import Serializable

✗ from rlp.sedes import Serializable

While `Serializable` is part of the 'sedes' (serialization/deserialization) module internally, it is exposed directly from the top-level `rlp` package for convenience.

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'...'`).

import rlp # Encode a simple byte string encoded_string = rlp.encode(b'ethereum') print(f"Encoded 'ethereum': {encoded_string}") # Decode it back decoded_string = rlp.decode(encoded_string) print(f"Decoded back: {decoded_string}") # Encode a list of byte strings and integers data = [b'dog', b'cat', b'elephant', 0, 15, 12345] encoded_list = rlp.encode(data) print(f"\nEncoded list: {encoded_list}") # Decode the list decoded_list = rlp.decode(encoded_list) print(f"Decoded list: {decoded_list}") # Encoding nested lists nested_data = [b'a', [b'b', b'c'], [b'd', [b'e', b'f']]] encoded_nested = rlp.encode(nested_data) print(f"\nEncoded nested: {encoded_nested}") decoded_nested = rlp.decode(encoded_nested) print(f"Decoded nested: {decoded_nested}")

Debug

Known issues

breakingThe 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.

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

affects: <3.0.0

gotchaWhen 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`.

fix

Always convert `str` to `bytes` using `my_string.encode('utf-8')` (or another appropriate encoding) before passing to `rlp.encode`.

affects: >=3.0.0

gotchaBe 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.

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

affects: All

gotchaThe 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.

fix

Explicitly use `[]` for an empty list and `b''` for an empty byte string to ensure the correct RLP encoding is generated.

affects: All

Errors

Common errors & fixes

TypeError: object of type <class 'str'> is not RLP serializable

The rlp library expects byte strings (`bytes`), not unicode strings (`str`), for RLP serialization.

fix

Convert unicode strings to byte strings using `.encode()` before encoding. For example, `rlp.encode(b'hello')` or `rlp.encode('hello'.encode('utf-8'))`.

rlp.DecodingError: RLP string is malformed

The provided byte string is not a valid RLP encoded structure, often due to corruption, truncation, or incorrect generation.

fix

Ensure the input byte string is a correctly RLP-encoded object. Verify the source of the RLP data or the encoding process.

ModuleNotFoundError: No module named 'rlp'

The 'rlp' library is not installed in the current Python environment, or the environment where the script is run does not have it.

fix

Install the 'rlp' library using pip: `pip install rlp`.

TypeError: object of type <class 'float'> is not RLP serializable

The rlp library can only serialize integers, byte strings, or lists/tuples containing these types, not floating-point numbers.

fix

Convert floats to integers (if appropriate, e.g., `int(3.14)`) or to a byte representation (e.g., `str(3.14).encode('utf-8')`) before encoding.

Upgrade

Version history

5.0.0latest on PyPI · released Aug 21, 2026

Audit

Dependencies

PythonrequiredRequires Python 3.8 or higher.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ethereum/pyrlp ↗

packagehttps://pypi.org/project/rlp/ ↗