mpytool - alternative CLI tool for MicroPython file management

[pavelrevak]

Hi everyone,

I've been working on a CLI tool called mpytool as an alternative to mpremote for file transfers and device interaction. I started writing it some years ago as a personal project to scratch my own itch.

Some features that might be useful:

• Fast transfers - optimized timing, auto-tuned chunk sizes, optional compression
• Clean Python API - usable as a library, not just CLI
• Robust connection handling - recovers from stuck REPL states
• General-purpose serial terminal - repl and monitor commands work standalone
• Completion - support in ZSH and BASH

Platforms: macOS, Linux and Windows (Windows untested)

GitHub: https://github.com/cortexm/mpytool
Install: pip install mpytool

If you're having connection issues with other tools, it might be worth trying.

Feedback welcome!

[peterhinch]

There is potential for name confusion with the official mpy-tool.

[Josverl]

@pavelrevak , on first look this seems like a nice combination of utilities.

Having an API is quite nice.
I did a very short test on Windows, and it is not untested - it does not work at all (at this time).

• no port detection
• no repl
• no basic file commands

The missing support for Windows is a disqualifier for me. An API is of no use unless I can be sure it works across all mainline OSes.

I also notice that you claim to skip exiting files better than mpremote , but I think you may have overlooked that mpremote has had that capability for quite some time.

Out of curiosity, why did you choose to create a separate tool , rather than to discuss and possibly contribute some of these features in a PR to mpremote ?

see: cortexm/mpytool#3

[peterhinch]

A personal observation.
Official mpremote has a killer feature which is the ability to issue

$ mpremote mount .

This is quite astonishingly useful and transformed the way I work with MicroPython. For example I support a number of fairly substantial repos. I can now use a single piece of hardware, with the Flash containing only tiny hardware definition files (one for each repo). I can run demos simply by moving to the relevant repo on the PC and issuing something like

$ mpremote mount . exec "import gui.demos.various"

No mass erasing the previous repo, no copying of files to the device.

A development environment that lacked this feature would be problematic.

[pavelrevak]

Thanks @peterhinch for the comments. Mounting a local filesystem should not be hard to implement in mpytool, because MicroPython provides a very good API for this.
I already have something partially implemented, but it’s not finished yet. I paused further development after noticing how slow it was.

Personally, I use another “killer” feature. Most of my development and testing is done on devices with external PSRAM (2MB+). Inside boot.py I implemented a simple filesystem stored as a dictionary structure: boot_ram.py

Then in my IDE I have a shortcut that copies all files from my project to : (in this case it copies them to the CWD: /ramfs).
mpytool is very fast at copying, so delays are minimal and the program runs almost like native code. Of course, this approach requires more system RAM. It uses as much RAM as the files on the disk take up.

---

by the way, Windows support is already done in latest release.

[Josverl]

Getting the PC to do it would be lightning quick, but I suspect it's not possible.

yes it it possible , but not currently implemented
it would need mpy-cross to do the compilation, and would need to probe for the version and optionally MCU architecture of the target device to compile for. Especially when using native code the mpy-cross produced .mpy version needs to match exactly

[peterhinch]

Is it on the roadmap?

The reason I questioned its practicality is that mpremote cp foo.py : needs to copy the file verbaitim while import foo issued on the target needs to create and copy the bytecode. Further, if Python code on the target opens foo.py on the mounted partition, f.readline() (etc) needs to return source lines. It wasn't obvious to me how mpremote might distinguish between these cases.

[andrewleech]

yes it it possible , but not currently implemented\nit would need mpy-cross to do the compilation, and would need to probe for the version and optionally MCU architecture of the target device to compile for. Especially when using native code the mpy-cross produced .mpy version needs to match exactly

I do have a proof of concept build of mpremote with this feature in it and working, it's quite effective for things like run to speed up the transfer.

There's a catch when using it in mount though; I initially hooked into the mounted filesystem handler so any time a py file is attempted to be imported it would intercept the os.stat call, say the py is not available and mpy-cross on the fly and respond yes to os.stat on the mpy of it. This works fine for import but means that it's anyone used mount to try to just copy a py file on it wouldn't work - the intercept says no to .py files.
There's some explicit logic in the import handing in micropython to try a .py file before a .mpy file, I'm not sure on the history of this but if it could be inverted then the mount / cp .py issue would be resolved as .mpy would be os.stat first when you import foo and I could just respond yes and give the mpy-cross on the fly. foo.py access wouldn't need to be affected.
Maybe I should raise my PR with the feature with this question about import order...

[Josverl]

IIRC the .py before .mpy is intended to allow patching of frozen files with on filesystem files. I think since v1.20 or so that can be done with changing sys.path, but not 100% sure

[pavelrevak]

You can't replace order. There is rule "development first", so py file has prioroty before compiled, which can be older. Micropython don't check time or anythink else. .mpy file is no cache like in cpython. In my mpytool import file - will import file.mpy but cat file.py works as well. Try it!

[sosi-deadeye]

You can tell that a lot of things have been optimized quite drastically. I'm referring to the bit shifting of sys.implementation._mpy.

For the start, you could do this:

deadeye@nexus ~]$ mpremote exec "import sys
sys_mpy = sys.implementation._mpy
arch = [None, 'x86', 'x64',
    'armv6', 'armv6m', 'armv7m', 'armv7em', 'armv7emsp', 'armv7emdp',
    'xtensa', 'xtensawin', 'rv32imc', 'rv64imc'][(sys_mpy >> 10) & 0x0F]
print('mpy version:', sys_mpy & 0xff)
print('mpy sub-version:', sys_mpy >> 8 & 3)
print('mpy flags:', end='')
if arch:
    print(' -march=' + arch, end='')
if (sys_mpy >> 16) != 0:
    print(' -march-flags=' + (sys_mpy >> 16), end='')
print()"

The output:

mpy version: 6
mpy sub-version: 3
mpy flags: -march=xtensawin

[pavelrevak]

Just for info, latest release mpytool v2.2.4 implements cp -m flag, which compiles .py files to .mpy using mpy-cross.
It detects the target device's mpy bytecode version and architecture, and compiles with correct -b and -march flags.

Compiled files are cached in __pycache__/file.mpy-{ver}-{march}.mpy.

boot.py and main.py are skipped (firmware looks them up by name).

If mpy-cross is not installed or compilation fails, it falls back to uploading .py files with a warning.

[pavelrevak]

@peterhinch latest release with some improvements v2.3.0:

mount

Mount local directory as VFS on device (/remote)

• Read/write support
• Mpy-cross integration - transparently serve compiled .mpy instead of .py
• Virtual symlinks (ln) - add submounts into mounted VFS
• Multiple simultaneous mounts with auto-recovery after soft reset
• Full file operations: seek, readline, rename
• CWD automatically changes to mountpoint; preserved on soft reset

[pavelrevak]

How mpy-cross compiling on demand with mount works

$ mpytool -dd mount -m ~/Work/mpy/sandbox -- repl
....
CMD: _mt_mount('/remote',0,16384)
CMD: os.chdir('/remote')
Mounted /Users/vlk/Work/mpy/sandbox on /remote (readonly, .mpy compilation)
CMD: os.chdir('/remote')
Changed CWD to /remote
EXIT RAW REPL
REPL (Ctrl+] to exit)
>>> import other
MOUNT: STAT: '/other' -> ENOENT
MOUNT: STAT: '/other.py' -> ENOENT (->mpy)         <-- 1
MOUNT: STAT: '/other.mpy' -> mode=0x8000 size=82   <-- 2
MOUNT: OPEN: '/other.mpy' mode=rb -> fd=0          <-- 3
MOUNT: READ: fd=0 n=32768 -> 82B
MOUNT: READ: fd=0 n=32768 -> 0B
MOUNT: CLOSE: fd=0 -> OK
other file imported

-m enable mpy-cross compilling (it detects version and platform)

1. although there is .py - mpytool will try to compile it and on success will send ENOENT, otherwise send ACK to download this file
2. send ACK
3. downloading mpy file

will compile file once and keep it in __pycache__ with some signature by version. before compiling it checks if this file exists and if is older than source .py then is recompiled..

[pavelrevak]

v2.3.3

although Windows is not my priority I made some fixes related to Windows.
also added CI tests on real HW (Linux and Windows)
and some other fixes

My question is: "What is missing you in this tool ?"

Thanks to @Josverl for bug reports

[Josverl]

Pavel,
Thanks for the quick fixes 👏.

I would like a way to list the connected devices, even if just one, and preferably excluding/omitting Bluetooth serial ports..

• mpremote devs | mpremote connect list (basic)
• mpflash list (filters BT mapped ports across OSes)

I juggle many devices and swap between Windows and WSL2, so am ever confused which port what board is connected to.
My personal goto is mpflash - but I think this would be handy as a quick sanitycheck in mpytool as well

[pavelrevak]

I would like a way to list the connected devices, even if just one, and preferably excluding/omitting Bluetooth serial ports..

That is great idea! but there are some undocumented commands and one is _ports, but this is used for completion only and don't print device details. Ok, I will add something documented with details.

$ mpytool _ports                  
/dev/cu.usbmodem101
/dev/cu.usbmodem1101

or use tab completion:

$ mpytool -p <tab>
/dev/cu.usbmodem101   /dev/cu.usbmodem1101

but yes, there are no device details

[pavelrevak]

v2.3.5

$ mpytool ports                       
/dev/cu.usbmodem1101    Espressif Device [dcda0c3005ac0000]
/dev/cu.usbmodem5   Espressif ESP32-C3/C6 [98:88:E0:3F:29:18]
/dev/cu.usbserial-0001  CP2102 USB to UART Bridge Controller [0001]

$ mpytool ports -i                    
/dev/cu.usbmodem1101    Espressif Device [dcda0c3005ac0000]
  esp32, 3.4.0; MicroPython v1.27.0-dirty on 2025-12-10
/dev/cu.usbmodem5   Espressif ESP32-C3/C6 [98:88:E0:3F:29:18]
  esp32, 3.4.0; MicroPython v1.27.0 on 2025-12-09
/dev/cu.usbserial-0001  CP2102 USB to UART Bridge Controller [0001]
  esp32, 3.4.0; MicroPython v1.27.0 on 2025-12-09

or zsh shell completion:

$ mpytool -p /dev/cu.usb <TAB>
/dev/cu.usbmodem1101 -- Espressif Device [dcda0c3005ac0000]
/dev/cu.usbmodem5 -- Espressif ESP32-C3/C6 [98:88:E0:3F:29:18]
/dev/cu.usbserial-0001 -- CP2102 USB to UART Bridge Controller [0001]

[pavelrevak]

Personally my preferred IDE is SublimeText, so, I created plugin for it which uses this mpytool.

It allow to copy file/s to device (also with .mpy compilation), backup/restore, monitor output, run current file, reset, port detection/selection and other commands.

Also uses own project file .mpyproject, where is defined what files will be send to device and other configuration stuff.