Install & Compatibility
Where this runs
tested against v1.2.12 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.026s · 22.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.024s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ScaleBytes
✓ from scalecodec.base import ScaleBytes
RuntimeConfiguration
✓ from scalecodec.type_registry import RuntimeConfiguration
MetadataVersioned
✓ from scalecodec.metadata import MetadataVersioned
✗ runtime_config.create_scale_object("MetadataVersioned") (for v2.0.0a+)
For `scalecodec` v2.x (alpha and future stable releases), `MetadataVersioned` is directly imported and instantiated as an object, replacing the `create_scale_object` method used in v1.x.
This quickstart demonstrates encoding and decoding a 'Compact' integer, a common SCALE type for large numbers. It shows the typical pattern of initializing a `RuntimeConfiguration` and using `create_scale_object` for type-specific encoding/decoding in `scalecodec` v1.x. For complex types, you would load a chain's metadata into the `RuntimeConfiguration`.
from scalecodec.base import ScaleBytes
from scalecodec.type_registry import RuntimeConfiguration
# Initialize a runtime configuration (required for decoding types based on metadata)
# For simple types, a basic config can be used.
# For complex types, load a specific chain's metadata using load_type_registry()
runtime_config = RuntimeConfiguration()
# Example: Encode a Compact integer
compact_int_value = 100000000000000
compact_encoder = runtime_config.create_scale_object("Compact<u128>")
encoded_data = compact_encoder.encode(compact_int_value)
print(f"Encoded {compact_int_value} (Compact<u128>): {encoded_data.to_hex()}")
# Example: Decode a Compact integer
encoded_hex_value = "0x0b00407a10f35a" # The SCALE encoding for 100,000,000,000,000
compact_decoder = runtime_config.create_scale_object("Compact<u128>")
decoded_value = compact_decoder.decode(ScaleBytes(encoded_hex_value))
print(f"Decoded {encoded_hex_value} (Compact<u128>): {decoded_value}")
Debug
Known issues
breakingVersion 2.0.0a (alpha) introduces a 'new from the ground up object based implementation' which fundamentally changes how types are handled and instantiated. This is a significant breaking change from v1.x's string-based type parsing.fixReview the v2.x documentation and migration guides once stable. Code relying on `runtime_config.create_scale_object("TypeName")` will need to be refactored to use direct object instantiation like `TypeName.new()` or similar patterns for v2.x. affects: 2.0.0a and higher
gotchaThe SCALE codec is not self-describing; it requires prior knowledge of the data's type definition for correct decoding. Attempting to decode data without the correct type context (e.g., from blockchain metadata) will lead to incorrect or failed decoding.fixAlways ensure your `RuntimeConfiguration` is initialized with the correct type registry or chain metadata for the specific data you are trying to decode. For Substrate chains, this typically involves loading the chain's `MetadataVersioned`.
affects: <2.0.0a
gotchaWhen decoding a byte array, the `decode()` method by default expects the entire byte stream to be consumed. If you are decoding a partial stream or a byte array with trailing data, this will raise an error.fixPass `check_remaining=False` to the `decode()` method if you expect valid trailing bytes after the intended object has been decoded. For example: `decoder.decode(scale_bytes, check_remaining=False)`.
affects: All versions
gotchaFor composite types (structures), the SCALE codec ignores field names; only the order of fields matters for encoding and decoding. Re-encoding data that was decoded with an assumed order into a different field order will result in a different (and likely incorrect) byte array.fixMaintain a consistent and correct ordering of fields for composite types according to the source (e.g., blockchain runtime metadata) to ensure predictable encoding and decoding behavior.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scalecodec'
The `scalecodec` Python library is not installed in your current environment.
fixInstall the library using pip: `pip install scalecodec`
ValueError: Bytes must be prefixed with 0x
A hexadecimal string value was provided to a `scalecodec` function (e.g., for `H256`, `Bytes`, `AccountId`) without the mandatory `0x` prefix.
fixPrepend `0x` to your hexadecimal string. For example, use `'0xabcdef...'` instead of `'abcdef...'`.
TypeError: object of type 'int' has no len()
An integer was passed to a `scalecodec` type (e.g., `H256`, `Bytes`, fixed-length arrays) that expects a bytes-like object or a `0x`-prefixed hexadecimal string.
fixConvert the integer to a `0x`-prefixed hexadecimal string (e.g., `f'0x{my_int:x}'`) or a padded bytes object (e.g., `my_int.to_bytes(length, 'little')`) before encoding. scalecodec.exceptions.SubstrateRequestException: Error decoding metadata: Invalid length of byte_string for compact_len
The Substrate metadata received from the node or provided manually is malformed, corrupted, or uses an unsupported SCALE compact encoding for a length field.
fixVerify the source of the metadata (e.g., Substrate node RPC endpoint), ensure the node is running a compatible version, or try upgrading `scalecodec` to the latest version to handle newer metadata formats. If manually providing metadata, re-verify its integrity and format.
Upgrade
Version history
1.2.12latest on PyPI · released Oct 16, 2025
Audit
Dependencies
No dependency data recorded yet.