{"id":5712,"library":"reedsolo","title":"Reed-Solomon Encoder/Decoder","description":"reedsolo is a pure-Python library providing a universal errors-and-erasures Reed-Solomon codec for data protection against errors and bitrot. It includes a fallback pure-Python implementation and an optional speed-optimized Cython/C extension. The library primarily focuses on burst-type errors, making it well-suited for data storage protection. The current stable version is 1.7.0, with a major 2.x branch actively in beta (2.1.1b1) introducing significant changes.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/tomerfiliba/reedsolomon","tags":["error-correction","reed-solomon","ecc","data-integrity","decoding","encoding","data-storage"],"install":[{"cmd":"pip install reedsolo","lang":"bash","label":"Stable (1.x branch, pure Python by default)"},{"cmd":"pip install reedsolo --install-option=\"--cythonize\" --verbose","lang":"bash","label":"Stable (1.x branch, with optional Cython extension - older pip)"},{"cmd":"pip install --config-setting=\"--build-option=--cythonize\" reedsolo","lang":"bash","label":"Stable (1.x branch, with optional Cython extension - pip 23.1+)"},{"cmd":"pip install reedsolo --pre","lang":"bash","label":"Beta (2.x branch, may include Cython extension)"}],"dependencies":[{"reason":"Required for compiling the optional C extension for significant speedups. Not installed by default in 1.x unless explicitly requested.","package":"Cython","optional":true}],"imports":[{"note":"Standard import for the pure-Python implementation.","symbol":"RSCodec","correct":"from reedsolo import RSCodec"},{"note":"Exception class for Reed-Solomon related errors.","symbol":"ReedSolomonError","correct":"from reedsolo import ReedSolomonError"},{"note":"Used when the optional Cython/C extension is successfully compiled and available. The module name changes from 'reedsolo' to 'creedsolo'.","wrong":"from reedsolo import creedsolo","symbol":"RSCodec","correct":"from creedsolo import RSCodec"}],"quickstart":{"code":"from reedsolo import RSCodec, ReedSolomonError\n\n# Initialize RSCodec with the number of error correction (ECC) symbols\n# 10 ECC symbols allow correction of up to 5 byte-level errors (nsym/2)\nrsc = RSCodec(10)\n\noriginal_message = b'hello world'\nprint(f\"Original: {original_message}\")\n\n# Encode the message\nencoded_message = rsc.encode(original_message)\nprint(f\"Encoded: {encoded_message}\")\n\n# Simulate some errors (e.g., change 'o' to 'X' in 'world')\ntampered_message = bytearray(encoded_message)\ntampered_message[4] = ord(b'X') # 'o' in 'hello'\ntampered_message[8] = ord(b'X') # 'o' in 'world'\ntampered_message[12] = ord(b'X') # ECC part\nprint(f\"Tampered: {tampered_message}\")\n\n# Decode and correct errors\ntry:\n    # decode returns (decoded_message, corrected_ecc_symbols, errata_positions)\n    decoded_message, _, _ = rsc.decode(tampered_message)\n    print(f\"Decoded: {decoded_message}\")\n\n    if original_message == decoded_message:\n        print(\"Decoding successful, message recovered.\")\n    else:\n        print(\"Decoding failed or original message not fully recovered.\")\n\nexcept ReedSolomonError as e:\n    print(f\"Decoding failed: {e}\")","lang":"python","description":"This quickstart demonstrates how to encode a message using a specified number of ECC symbols and then decode it after introducing simulated errors. The `RSCodec` class handles the core encoding and decoding operations. The output type (bytearray or bytes) is matched to the input type."},"warnings":[{"fix":"For new projects, carefully review the 2.x migration guide on PyPI or GitHub. For existing v1.x projects, consider staying on the 1.x stable branch or refactor data handling to use `bytearray` consistently and update Cython if using the C extension. If using `cimport creedsolo` with Cython, the path changes to `cimport creedsolo.creedsolo`.","message":"The 2.x beta branch (e.g., v2.1.1b1) introduces significant breaking changes. It requires Cython >= 3.0.0b2 for its speed-optimized C extension and enforces stricter type usage, primarily expecting `bytearray` or `cpython array` objects for data, whereas v1.x was more flexible with list objects.","severity":"breaking","affected_versions":"2.x.x (beta releases)"},{"fix":"Install with `pip install --upgrade reedsolo --install-option=\"--cythonize\" --verbose` (for older pip) or `pip install --config-setting=\"--build-option=--cythonize\" reedsolo` (for pip 23.1+). This will attempt to build `creedsolo.pyx` if Cython and a C compiler are available.","message":"By default, `reedsolo` (v1.x) installs only the pure-Python implementation. To utilize the faster Cython/C extension, you must explicitly request its compilation during installation, requiring Cython and a C++ compiler.","severity":"gotcha","affected_versions":"1.7.0 and earlier 1.x, some 2.x pre-releases"},{"fix":"Manually split your longer data into chunks that fit within the (255 - nsym) data bytes limit, encode each chunk separately, and then reassemble/decode them individually.","message":"The default Galois field GF(2^8) used by reedsolo means that the maximum total message length (data + ECC symbols) is 255 bytes. For messages longer than this, you must implement chunking to break the data into smaller, manageable blocks for encoding and decoding.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For critical applications requiring high integrity, consider using additional error detection mechanisms like hashing functions (e.g., SHA256) in parallel with Reed-Solomon. Use Reed-Solomon for repair, and the hash for a more robust integrity check.","message":"If the number of errors or erasures exceeds the Reed-Solomon code's correction capability (Singleton bound), the `check()` method or even the decoder might return a mathematically valid but still incorrect/tampered message, rather than raising an error. This is a characteristic of Reed-Solomon codes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}