mutf8

library1.1.0pypypi✓ verified 22d ago

This package provides fast pure-Python and optional C implementations for encoding and decoding MUTF-8 and CESU-8 character encodings. MUTF-8 is a variant of UTF-8 primarily encountered in Java Virtual Machine (JVM) contexts. It offers significant performance gains with its C extension, falling back to a pure-Python version if the C extension cannot be built. The current version is 1.0.6, released in late 2021, and the project is in a maintenance phase.

serialization

pip install mutf8

github ↗package ↗

INSTALL

IMPORT

SIG · MUTF8

mutf8

serializationpythonv1.1.0

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.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.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

encode_modified_utf8

✓ from mutf8 import encode_modified_utf8

decode_modified_utf8

✓ from mutf8 import decode_modified_utf8

This quickstart demonstrates how to encode a Python string (including one with a null character) into MUTF-8 bytes and then decode it back using the `mutf8` library. MUTF-8 handles null characters and supplementary characters differently than standard UTF-8.

from mutf8 import encode_modified_utf8, decode_modified_utf8 # A string with a null character, which MUTF-8 handles differently original_string = "Hello, \u0000 World!" # Encode the string to MUTF-8 bytes mutf8_bytes = encode_modified_utf8(original_string) print(f"Encoded MUTF-8 bytes: {mutf8_bytes!r}") # Decode the MUTF-8 bytes back to a Python unicode string decoded_string = decode_modified_utf8(mutf8_bytes) print(f"Decoded string: {decoded_string!r}") # Example with a supplementary character (encoded as surrogate pairs in MUTF-8) sup_char_string = "\U0001F600" mutf8_sup_char_bytes = encode_modified_utf8(sup_char_string) print(f"Encoded supplementary char: {mutf8_sup_char_bytes!r}") decoded_sup_char_string = decode_modified_utf8(mutf8_sup_char_bytes) print(f"Decoded supplementary char: {decoded_sup_char_string!r}")

Debug

Known issues

gotchaMUTF-8 is a specific variant of UTF-8, primarily used in Java environments. It differs from standard UTF-8 in two key ways: the null character (U+0000) is encoded as a two-byte sequence (`0xC0 0x80` instead of `0x00`), and supplementary characters (code points above U+FFFF) are encoded as two three-byte sequences (via UTF-16 surrogate pairs) instead of a single four-byte sequence. Using Python's built-in `utf-8` codecs for MUTF-8 data will lead to incorrect results.

fix

Always use `mutf8.encode_modified_utf8` and `mutf8.decode_modified_utf8` when working with MUTF-8 encoded data, especially when interfacing with Java systems.

affects: All versions

gotchaThe `mutf8` library provides a C extension for significant performance improvements (20x to 40x faster) over its pure-Python implementation. If a C99-compatible compiler is not available during installation, the library will silently fall back to the slower pure-Python version. This can lead to unexpected performance bottlenecks.

fix

Ensure a C99-compatible compiler is installed and available in your environment before installing `mutf8` to leverage the performance benefits of the C extension. Check installation logs for successful C extension compilation.

affects: All versions with C extension

deprecatedVersions of `mutf8` prior to `1.0.3` provided less precise and less descriptive `UnicodeDecodeErrors`. This made debugging issues with malformed MUTF-8 input more challenging.

fix

Upgrade to `mutf8` version `1.0.3` or newer to benefit from improved error reporting and more accurate error locations in `UnicodeDecodeErrors`.

affects: < 1.0.3

breakingSupport for Python 3.5 has been dropped in recent versions of `mutf8`. Attempting to install or use newer versions on Python 3.5 will likely fail.

fix

Upgrade your Python environment to version 3.6 or newer to continue using `mutf8`.

affects: > unknown (post-Python 3.5 EOL)

Errors

Common errors & fixes

UnicodeDecodeError: 'mutf8' codec can't decode byte 0x... in position ...: invalid start byte

This error occurs when the `mutf8` decoder encounters a byte sequence that does not conform to the Modified UTF-8 (MUTF-8) specification, indicating malformed MUTF-8 input or an attempt to decode non-MUTF-8 data. Older versions (prior to 1.0.3) provided less precise error messages for this.

fix

Ensure the input data is genuinely MUTF-8 encoded. If dealing with Java systems, verify the MUTF-8 encoding process. If using an older `mutf8` version, upgrade to 1.0.3 or newer for improved error reporting. Carefully inspect the bytes around the reported position to identify the malformed sequence.

StopIteration

This specific error can occur during the decoding process, particularly in scenarios where the `mutf8` decoder's internal iterator for byte sequences is exhausted prematurely due to malformed or incomplete MUTF-8 input, especially when parsing multi-byte characters.

fix

Verify the integrity and completeness of the MUTF-8 byte sequence being decoded. This error often points to truncated or severely malformed input that causes the decoder to expect more bytes than are available in a sequence.

ImportError: No module named 'mutf8.cmutf8'

The `mutf8` library provides an optional C extension (`cmutf8`) for significant performance gains. This error occurs when a developer explicitly tries to import the C extension (e.g., `from mutf8.cmutf8 import ...`) but it was not successfully built or installed, often due to the absence of a C99-compatible compiler during `pip install`.

fix

Ensure a C99-compatible compiler (like GCC or MSVC) is installed and available in your environment before installing `mutf8`. Then, reinstall the library using `pip install --no-binary :all: mutf8` to force a source build, or simply `pip install mutf8` after confirming your compiler setup. If the C extension is not critical for your use case, you can continue using the pure-Python fallback by importing directly from `mutf8` (e.g., `from mutf8 import encode_modified_utf8`).

Upgrade

Version history

1.1.0latest on PyPI · released Jul 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttp://github.com/TkTech/mutf8 ↗

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