mpremote Cheatsheet

Quick reference for the most common mpremote commands.

---

Installation

mpremote is a Python package. You need Python 3 installed first.

pip install mpremote

Verify it works:

mpremote --version

Using a virtual environment (recommended)

If your system Python restricts global installs (error: externally-managed-environment), or you want a clean setup, use a virtual environment:

python -m venv ~/pico-env
source ~/pico-env/bin/activate    # Linux/Mac
# ~/pico-env\Scripts\activate     # Windows
pip install mpremote

You need to activate the environment each time you open a new terminal:

source ~/pico-env/bin/activate

To make this automatic, add the source line to your ~/.bashrc or ~/.zshrc.

Platform notes:

OS	Notes
Linux	You may need serial port access: sudo usermod -a -G dialout $USER (then log out and back in)
macOS	Works out of the box after pip install
Windows	Use Command Prompt or PowerShell. If pip is not found, try py -m pip install mpremote

If you get command not found after installing, make sure your Python scripts directory is on your PATH, or use python -m mpremote instead.

---

Connection

# List connected Picos
mpremote connect list

# Connect to specific port
mpremote connect /dev/ttyACM0

# Auto-connect (finds first Pico)
mpremote

---

Running Code

# Run script (doesn't save to Pico)
mpremote connect /dev/ttyACM0 run script.py

# Interactive REPL
mpremote connect /dev/ttyACM0 repl

REPL Shortcuts:

Key	Action
Ctrl+C	Stop running code
Ctrl+D	Soft reset
Ctrl+X	Exit mpremote

---

File Operations

# List files on Pico (root)
mpremote connect /dev/ttyACM0 ls

# List files in lib folder
mpremote connect /dev/ttyACM0 ls lib/

# Copy file TO Pico (note the colon prefix)
mpremote connect /dev/ttyACM0 cp local.py :remote.py

# Copy file FROM Pico
mpremote connect /dev/ttyACM0 cp :remote.py local.py

# View file contents
mpremote connect /dev/ttyACM0 cat main.py

# Delete file
mpremote connect /dev/ttyACM0 rm main.py

# Create directory
mpremote connect /dev/ttyACM0 mkdir lib

---

Device Control

# Soft reset (restart)
mpremote connect /dev/ttyACM0 reset

# Hard reset
mpremote connect /dev/ttyACM0 bootloader

---

Common Workflows

Deploy main.py

mpremote connect /dev/ttyACM0 cp my_code.py :main.py
mpremote connect /dev/ttyACM0 reset

Deploy library

mpremote connect /dev/ttyACM0 mkdir lib
mpremote connect /dev/ttyACM0 cp picobot.py :lib/picobot.py

Quick test (no save)

mpremote connect /dev/ttyACM0 run test.py

Check what's on Pico

mpremote connect /dev/ttyACM0 ls
mpremote connect /dev/ttyACM0 cat main.py

---

Shorthand

If you only have one Pico connected:

# These are equivalent:
mpremote connect /dev/ttyACM0 run script.py
mpremote run script.py

---

Troubleshooting

Error	Solution
"no MicroPython device"	Check USB connection, try different cable
"permission denied"	sudo usermod -a -G dialout $USER then logout/login
"device busy"	Close Thonny or other serial programs
"cannot write"	Pico might be in BOOTSEL mode, reconnect normally

---

← Reference Index | Deployment Guide