QUERY · ISSUE

mpremote cp fails with equals sign (=) in filename

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

bugtoolsunicode

Port, board and/or hardware

Any platform (Windows, Linux, macOS) - affects mpremote tool when copying files with equals sign (=) in the filename.

MicroPython version

mpremote 1.27.0
Tested against MicroPython unix port and ESP32

The issue is in mpremote's argument parser, not in MicroPython firmware.

Reproduction

Create a test file with an equals sign in the name:

mkdir unicode_test
echo "test" > "unicode_test\H2O_E=mc2.txt"

Attempt to copy to MicroPython device:

mpremote cp "unicode_test\H2O_E=mc2.txt" ":/test.txt"

Observe the error.

Expected behaviour

mpremote cp should successfully copy files with equals signs in filenames. The argument parser should not interpret = within filenames as key-value separators.

Filenames with = are valid on all major operating systems (Windows, Linux, macOS) and should be supported.

Observed behaviour

The command fails because mpremote's argument parser interprets the = character as a key-value separator, truncating the filename:

Input: H₂O_E=mc².txt
Parsed as: key=H₂O_E, value=mc².txt
Error: "unexpected argument" because the truncated filename doesn't match expected syntax

Additional Information

mpremote's argument parser (likely in main.py or the command dispatch logic) splits arguments on = to support key-value style arguments. This incorrectly affects filenames that legitimately contain the = character.

Affected Filenames

Any filename containing:

Equals sign: = (U+003D)

Common examples:

E=mc².txt
a=b.log
key=value.json
base64==data.bin

Suggested Fix

Modify the argument parser to not split on = within file path arguments. Options include:

Stop splitting on = for positional arguments - Only use = splitting for named/keyword arguments
Check if the argument is a valid file path first - If the argument exists as a file, don't split it
Require --key=value syntax - Only split on = when preceded by --

Code of Conduct

Yes, I agree

CANDIDATE · PULL REQUEST

Fix multiple unicode issues in mpremote.

closedby Josverlopened 2026-01-11updated 2026-02-20

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

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