QUERY · ISSUE

mpremote fails with UnicodeEncodeError on Windows legacy consoles (cp1252)

openby Josverlopened 2026-01-07updated 2026-01-09

bugtoolsunicode

Port, board and/or hardware

Windows (any hardware) - affects mpremote tool when run on Windows with legacy console (cp1252 or similar encoding).

MicroPython version

mpremote 1.27.0
Python 3.11.9 /3.13.1 (host)
Tested against MicroPython 1.27.0 RP2, ESP32

Reproduction

This issue only occurs with legacy Windows consoles that use cp1252 or similar encodings. Modern terminals (Windows Terminal, VS Code) use UTF-8 by default and are not affected.

To reproduce, you must use a legacy console:

Open legacy cmd.exe (not Windows Terminal) or configure PowerShell to use cp1252:
```
# Force legacy encoding in Python
$env:PYTHONIOENCODING = "cp1252"
```

Create test files with non-ASCII characters:

mkdir unicode_test
echo "test" > "unicode_test\Владимир_Петров.txt"

Use mpremote to copy:
```
mpremote cp -rv unicode_test :
```

Alternatively, the issue can be demonstrated with this Python snippet:

import sys
sys.stdout.reconfigure(encoding='cp1252')
print('Владимир_Петров.txt')  # Raises UnicodeEncodeError

Expected behaviour

mpremote cp should successfully copy files with Unicode characters in filenames on Windows. The tool should handle all Unicode characters in console output without raising encoding errors.

CPython's print() should use UTF-8 or properly handle the console encoding.

Observed behaviour

The command fails immediately with:

UnicodeEncodeError: 'charmap' codec can't encode characters in position X-Y: character maps to <undefined>

The file is not copied.

Additional Information

Workaround

Set the PYTHONIOENCODING environment variable before running mpremote:

$env:PYTHONIOENCODING = "utf-8"
mpremote connect COM3 cp -r . :

Or add to PowerShell $PROFILE for persistence:

$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONUTF8 = "1"

Suggested Fix

Force UTF-8 encoding in mpremote on Windows:

import sys
import io

if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')

This would be a minimal change in the mpremote initialization code.

Code of Conduct

Yes, I agree

CANDIDATE · PULL REQUEST

Fix multiple unicode issues in mpremote.

openby Josverlopened 2026-02-20updated 2026-02-21

toolsunicode

Summary

This pull request addresses multiple issues related to the handling of special characters and Unicode in the mpremote tool. It fixes the escaping of quotes in filenames, ensures proper parsing of filenames containing equals signs, and resolves Unicode encoding errors on Windows consoles. These improvements enhance the usability of mpremote when dealing with diverse file names and character sets.

Unicode-safe Windows console output: Detects modern consoles, sets UTF-8 code pages, wraps stdout/stderr when needed, and uses raw UTF-8 writes when possible; legacy consoles now handle split UTF-8 sequences safely.
Robust stdout handling: Buffers partial UTF-8 sequences and strips CTRL-D without losing characters, improving REPL/output correctness for multibyte text.
Safer path quoting: Filesystem commands now use repr-based quoting so filenames with quotes, backslashes, or Unicode work correctly (including equals-sign parsing).
CLI parsing fix: Command expansion no longer misinterprets arguments containing =, preventing unexpected-argument errors.
Transport write safety: Converts strings to UTF-8 bytes before writing to avoid encoding errors when writing unicode content to a host folder using mpremote mount <folder>

Fixes: #13055
Fixes: #15228
Fixes: #18658
Fixes: #18657

This is a re-submit of #18670 which was unrecoverably closed due to user error.

</p>
</details>

Testing

New test support: Adds ramdisk helper, enhanced test runner (device selection, skip handling), and Unicode/special-character coverage in the mpremote test suite.
New unicode tests have been added to the mpremote test suite, covering the scenarios mentioned in the issues.
It should be noted that the current CI setup does not provide for Windows testing, so manual verification has been essential for confirming the fixes.

Manual testing was conducted on Windows pwsh , cmd.exe, MinGW and Linux in WSL2.

Manual testing was needed due to the lack of Windows support in the bash based testing framework, ensuring that the fixes work as intended across different environments.
Also tests for the mpremote REPL and Console cannot be not covered by the bash test suite.

I started work of a pytest configuration for mpremote to adds the ability to test the REPL and Console, parts that the bash suite is unable to test at all.
That will be submitted in a separate PR once stable across multiple platforms.

Trade-offs and Alternatives

The changes made do not introduce significant trade-offs. The improvements in Unicode handling may slightly increase the complexity of the code, but they are necessary for robust functionality. Alternative approaches were considered, such as using different quoting mechanisms, but the current solutions provide the best balance of compatibility and simplicity.