mpremote

List all connected MicroPython devices

$ mpremote connect list

$ mpremote connect [device]

$ mpremote run [path/to/script.py]

$ mpremote mount [path/to/directory]

$ mpremote mip install [package]

mpremote [OPTIONS] COMMAND [ARGS...]

--device
    Specifies the serial port path to the MicroPython device (e.g., /dev/ttyUSB0 on Linux or COM3 on Windows).

--baud
    Sets the serial communication baud rate (default typically 115200).

--wait
    Waits for the device to connect for a specified timeout in seconds. Useful for devices that take time to boot.

--no-wait
    Disables waiting for the device to connect, proceeding immediately.

-v, --verbose
    Enables verbose output, providing more detailed information about operations and connection status.

--version
    Displays the mpremote tool version and exits.

repl
    Enters the MicroPython Read-Eval-Print Loop (REPL), allowing interactive execution of Python commands directly on the device.

shell
    Provides an interactive shell-like interface for navigating and managing the device's filesystem.

fs
    A group of commands for various filesystem operations on the MicroPython device. Common subcommands include ls, cp, cat, rm, mkdir, rmdir.

ls [remote_path]
    Lists contents of a directory on the MicroPython device. If remote_path is omitted, lists the current directory.

cp [local_path] [remote_path]
    Copies files or directories between the host computer and the MicroPython device. Supports recursive copy with -r.

cat
    Displays the content of a specified file on the MicroPython device to standard output.

rm
    Removes a specified file on the MicroPython device's filesystem.

mkdir
    Creates a new directory on the MicroPython device's filesystem.

rmdir
    Removes an empty directory on the MicroPython device's filesystem.

run
    Executes a Python script from the host computer directly on the MicroPython device.

exec
    Executes a short Python code snippet directly on the MicroPython device without creating a file.

mip
    Manages MicroPython packages using the MicroPython Package Installer. For example, mip install to install a library.

reset
    Performs a soft reset of the MicroPython board, restarting the MicroPython interpreter.

boot
    Performs a clean hard reboot of the device, similar to pressing the reset button.

df
    Displays the disk usage (free space) on the MicroPython device's filesystem.

mount
    Mounts a local directory on your host computer as a virtual filesystem on the MicroPython device, allowing direct access to local files.

unmount
    Unmounts the previously mounted virtual filesystem from the device.

mpremote is the official command-line tool for interacting with MicroPython-enabled microcontrollers connected via a serial port (typically USB). It provides a versatile set of functionalities, allowing users to execute Python code directly on the device, transfer files to and from the device's filesystem, manage packages using mip (MicroPython Package Installer), and access the MicroPython REPL (Read-Eval-Print Loop). It streamlines the development workflow for MicroPython projects by offering a robust way to manage files, debug code, and administer the device without needing to reflash the firmware repeatedly. mpremote acts as a bridge, enabling seamless communication and control over embedded MicroPython applications from a host computer.

mpremote requires the MicroPython device to be connected via a serial port and powered on. Proper serial port permissions are necessary (e.g., user in dialout group on Linux, or administrator privileges for COM ports on Windows). The device's serial port path can vary significantly and needs to be specified with --device. Occasional disconnections or unresponsive behavior may occur, sometimes requiring a manual device reset or re-plugging.

mpremote provides robust commands (e.g., ls, cp, cat, rm, mkdir, rmdir) to manage files and directories directly on the MicroPython device's internal flash storage. These commands mirror common Linux file system commands for ease of use in embedded development workflows, allowing seamless interaction with the device's storage.

The mount command allows a local directory on your host computer to appear as a virtual filesystem on the connected MicroPython device. This feature is incredibly useful for rapid development and testing, as changes to local files are immediately reflected and accessible on the device without needing to copy them explicitly, streamlining iteration cycles.

Integration with mip (MicroPython Package Installer) enables easy installation of libraries directly from PyPI, GitHub, or local sources onto the MicroPython device. This significantly simplifies dependency management and software provisioning for embedded projects, allowing developers to extend device functionality with pre-built modules efficiently.

mpremote emerged as the official, unified command-line tool within the MicroPython project to provide a consistent and robust way to interact with MicroPython devices. It aims to supersede various community-contributed tools like ampy or rshell by integrating core functionalities directly into the MicroPython ecosystem. Its development reflects MicroPython's maturation, offering a single, official utility for tasks ranging from file management and script execution to package installation (mip) and direct REPL access, simplifying the developer experience.

ampy(1), rshell(1), screen(1), minicom(1)