Install mpremote and connect over USB

mpremote is a laptop command-line tool for communicating with a MicroPython board over USB. Use it when your instructor assigns a USB activity. Ordinary browser play only needs the Wi-Fi connection guide. Install tools while connected to the internet, before joining Pocket CTF Wi-Fi.

1. Check whether mpremote is available

Open Terminal on Linux or macOS, or PowerShell on Windows, and run:

mpremote version

A version number means the tool is installed and available in this terminal; skip to step 3. This check does not need a board. If you see “command not found” or “not recognized,” the tool is missing or its folder is absent from PATH (the folders your terminal searches for commands).

To locate the command, use command -v mpremote on Linux/macOS or Get-Command mpremote in PowerShell. If you previously installed it inside a Python virtual environment, activate that environment first and retry.

2. Install on your laptop

The following commands install laptop software; they do not change board files. pipx installs Python command-line applications in their own environments.

Linux: apt, dnf, yum, or pacman

Choose the commands for your distribution to install pipx:

Distribution / package manager	Commands
Ubuntu / Debian (`apt`)	`sudo apt update`, then `sudo apt install pipx`
Fedora (`dnf`)	`sudo dnf install pipx`
Systems using `yum`	`sudo yum install pipx`, if available in your configured repositories
Arch Linux (`pacman`)	`sudo pacman -Syu python-pipx`

Then install mpremote as your normal user:

pipx install mpremote
pipx ensurepath

Close and reopen your terminal, then run mpremote version. If your distribution cannot find pipx, use the virtual environment option below. On a managed classroom laptop, ask the instructor to provide missing system packages.

Linux fallback: a Python virtual environment

With Python 3 and its virtual environment support installed:

python3 -m venv ~/.venvs/mpremote
source ~/.venvs/mpremote/bin/activate
python -m pip install mpremote
mpremote version

On Debian/Ubuntu, install missing prerequisites with sudo apt install python3 python3-venv. Activate this environment again in each new terminal before using mpremote.

Windows: PowerShell

Check Python with py --version. If it is missing, install Python 3 from python.org, reopen PowerShell, and retry. Then run:

py -m pip install --user pipx
py -m pipx install mpremote
py -m pipx ensurepath

Close and reopen PowerShell, then run mpremote version.

macOS: Homebrew

If Homebrew is installed:

brew install pipx
pipx install mpremote
pipx ensurepath

Reopen Terminal and run mpremote version.

3. Find your USB port

Connect your assigned board with a USB data cable. List ports without changing the board's files or resetting it:

mpremote devs

System	Default port used in this guide
Linux	`/dev/ttyACM0`
Windows	`COM5`
macOS	Use the `/dev/cu.usbmodem...` port shown by `mpremote devs`

These are example defaults, not guaranteed OS assignments. If the list shows a different port for your board, substitute that exact name. Windows also lists the assigned COM number in Device Manager under Ports (COM & LPT).

When your instructor asks you to open the MicroPython console (REPL), use:

# Linux
mpremote connect /dev/ttyACM0 repl

# Windows
mpremote connect COM5 repl

Exit mpremote with Ctrl+]. Opening the console does not write board files; Ctrl+C interrupts the running board program, so use it only as directed during the USB activity.

Quick fixes

Problem	What to do
Installed, but command still missing	Reopen the terminal after `pipx ensurepath`, or activate the virtual environment used for installation.
No board in `mpremote devs`	Try a USB data cable and another USB socket; ask the instructor if it still does not appear.
Port busy	Close other serial consoles, including Thonny or another `mpremote` session.
Linux permission denied	Ask the instructor to check your serial-port group permissions; group changes require a new login.
Wrong port	Run `mpremote devs` again after reconnecting and use the displayed port.

Installation references: MicroPython mpremote documentation, pipx installation guide, and Python Packaging guide.