mpremote cp fails with equals sign (=) in filename
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².txta=b.logkey=value.jsonbase64==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=valuesyntax - Only split on=when preceded by--
Code of Conduct
Yes, I agree
mpremote fails with UnicodeEncodeError on Windows legacy consoles (cp1252)
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