MicroPython
mpremote CLI Guide
mpremote is the official MicroPython command-line tool for managing your board — running scripts, transferring files, and accessing the REPL — all from your terminal without needing an IDE.
Installation
shell
# Recommended: install with pipx (isolated environment)
pipx install mpremote
# Alternative: install with pip
pip install mpremote
# Verify
mpremote --version
Connecting to Your Board
shell
# Auto-detect and connect to the first available MicroPython board
mpremote
# Connect to a specific port
mpremote connect /dev/ttyUSB0 # Linux
mpremote connect /dev/cu.SLAB_USBtoUART # macOS
mpremote connect COM3 # Windows
After connecting, you'll enter the interactive REPL:
text
MicroPython v1.xx.x on 2025-xx-xx; ESP32 module
>>>
Exit with Ctrl+] or Ctrl+X.
Running Scripts
shell
# Run a script on the board (board's filesystem, not local)
mpremote run main.py
# Run a local script directly on the board (doesn't write to board filesystem)
mpremote exec "print('Hello from mpremote')"
# Run a local Python file on the board
mpremote run mylocal_script.py
File Management
Copy Files to/from Board
shell
# Upload a file to the board
mpremote cp main.py :main.py
# Shorthand: mpremote cp localfile.py :remotepath.py
# Upload an entire folder
mpremote cp -r ./lib :lib
# Download a file from the board
mpremote cp :main.py ./downloaded_main.py
# Download an entire folder from board
mpremote cp -r :lib ./local_lib/
List Files
shell
# List root directory of the board
mpremote ls
# List a specific directory
mpremote ls :lib/
Create Directories
shell
# Create a directory on the board
mpremote mkdir :config
mpremote mkdir :lib/sensors
Delete Files
shell
# Delete a file from the board
mpremote rm :old_script.py
# Delete a directory (must be empty)
mpremote rmdir :old_dir
# Remove a directory and all contents (use with caution)
mpremote rm -r :old_dir
Chaining Commands
mpremote supports chaining multiple commands in one invocation:
shell
# Upload a file and then run it
mpremote cp main.py :main.py + run main.py
# Connect to specific port, upload, run, and open REPL
mpremote connect /dev/ttyUSB0 cp src/main.py :main.py + run main.py + repl
# Upload library files and main, then reboot
mpremote cp -r lib :lib + cp main.py :main.py + reset
REPL and Terminal
shell
# Open the interactive REPL
mpremote repl
# Open REPL with a capture file (saves all output to a log)
mpremote repl --capture log.txt
# Open REPL with injected startup code
mpremote repl --inject-code "import webrepl; webrepl.start(password='analog')"
Useful Commands Reference
shell
# Reset the board (soft reset — like pressing Ctrl+D in REPL)
mpremote reset
# Hard reset (like pressing the physical reset button)
mpremote hard-reset
# Get board info
mpremote exec "import sys; print(sys.implementation)"
# Check free memory
mpremote exec "import gc; gc.collect(); print(gc.mem_free(), 'bytes free')"
# Install a MicroPython package from micropython-lib
mpremote mip install urequests
mpremote mip install ssd1306
mpremote mip install aiohttp
# List available mip packages
mpremote mip list
# Get filesystem stats
mpremote exec "import uos; print(uos.statvfs('/'))"
Automating Deployment
mpremote is excellent for automating deployment scripts:
shell
#!/bin/bash
# deploy.sh — Deploy MicroPython project to board
BOARD_PORT="/dev/ttyUSB0"
echo "📦 Uploading library files..."
mpremote connect $BOARD_PORT cp -r lib :lib
echo "📤 Uploading main application..."
mpremote connect $BOARD_PORT cp main.py :main.py
echo "⚙️ Uploading config..."
mpremote connect $BOARD_PORT cp config.json :config.json
echo "🔄 Resetting board..."
mpremote connect $BOARD_PORT reset
echo "✅ Deployment complete!"
Make it executable and run:
shell
chmod +x deploy.sh
./deploy.sh
VS Code Integration
If you prefer VS Code, install the MicroPico extension (for Pico) or Pymakr extension (for ESP32) which use mpremote under the hood:
- Open Extensions (
Ctrl+Shift+X) - Search "MicroPico" (Pico boards) or "Pymakr" (ESP32/generic)
- Install and connect your board
- Enjoy file syncing and REPL inside VS Code
mpremote Shorthand Notation
| Symbol | Meaning |
|---|---|
:file.py | File on the board |
file.py | File on your computer |
: (colon only) | Root of the board's filesystem |
+ | Chain next command after current |
Troubleshooting
mpremote: device not found
Specify the port explicitly:
shell
mpremote connect /dev/ttyUSB0
mpremote connect COM3 # Windows
Failed to connect: timeout
The board may be stuck in a running loop. Hold the BOOTSEL/BOOT button or reset the board, then try again.
Files uploaded but not running on boot
Make sure your main file is saved as main.py (not Main.py or main.txt). MicroPython is case-sensitive.
mpremote mip install fails
Your board may not be connected to Wi-Fi. Install packages manually:
shell
# Download the package file first, then copy it
mpremote cp urequests.py :urequests.py
Complete Workflow Example
shell
# 1. Start a new project
mkdir my_iot_project && cd my_iot_project
# 2. Create project structure locally
mkdir lib
touch main.py boot.py config.json lib/wifi.py
# 3. Write your code locally using VS Code or any editor
# 4. Deploy to board
mpremote cp boot.py :boot.py
mpremote cp config.json :config.json
mpremote cp lib/wifi.py :lib/wifi.py
mpremote cp main.py :main.py
# 5. Test with REPL
mpremote repl