Repository navigation
install
Install from GitHub with uv or pip (not PyPI), per-OS prerequisites, and USB access on Linux.
Do not
pip install mbtoolsfrom PyPI. That name belongs to an unrelated project. Always install from GitHub.
| Python | 3.10 or newer |
| Dependencies |
pyserial, intelhex, pyocd, zeroconf, pyzmq. All install as wheels; no compiler needed |
git |
only if you use a git+https:// URL. The tarball URL below doesn't need it |
| Verified on | 64-bit Debian 13 (Raspberry Pi, aarch64), Ubuntu 24.04 (x86_64), macOS 15. Windows: not hardware-verified |
Per OS:
-
Debian / Ubuntu / Raspberry Pi OS:
sudo apt install python3 python3-venv git. You need the udev rule described below for non-root USB access. -
macOS: Python 3.10+ from python.org, Homebrew or
uv. No drivers. -
Windows 10/11: Python 3.10+ from python.org or
py. No drivers (DAPLink uses in-box USB drivers). Not hardware-verified.
git+https://github.com/League-Microbit/mbtools.git # latest main
git+https://github.com/League-Microbit/mbtools.git@<tag> # pinned
https://github.com/League-Microbit/mbtools/archive/refs/heads/main.tar.gz # no git needed
To list tags, run
git ls-remote --tags https://github.com/League-Microbit/mbtools.git.
Versions look like 0.YYYYMMDD.N. The per-user default paths and the
no-default-route fix are only in builds after v0.20260924.2.
A fixed interpreter path, independent of anyone's home directory. The service files on the other pages assume it.
# pip
sudo python3 -m venv /opt/mbtools
sudo /opt/mbtools/bin/pip install "git+https://github.com/League-Microbit/mbtools.git"
# or uv (sudo's PATH usually lacks ~/.local/bin, so pass the full path)
UV="$(command -v uv)"
sudo "$UV" venv --python /usr/bin/python3 /opt/mbtools
sudo "$UV" pip install --python /opt/mbtools/bin/python "git+https://github.com/League-Microbit/mbtools.git"
# put the four commands on everyone's PATH
sudo ln -sf /opt/mbtools/bin/mbregistry /opt/mbtools/bin/mbdeploy \
/opt/mbtools/bin/mbserial /opt/mbtools/bin/mbrelay /usr/local/bin/Then set up the service for your OS: Linux, macOS, Windows.
uv tool install "git+https://github.com/League-Microbit/mbtools.git" # commands land in ~/.local/bin
# or
python3 -m venv ~/.local/share/mbtools
~/.local/share/mbtools/bin/pip install "git+https://github.com/League-Microbit/mbtools.git"A client-only machine (no boards plugged in) still needs a local
mbregistry run to reach peers' boards, because clients always ask their
local daemon first.
git clone https://github.com/League-Microbit/mbtools.git && cd mbtools
uv sync # .venv with mbtools (editable) + dev deps
uv run mbregistry --help
uv run pytestmbregistry --help && mbdeploy --help && mbserial --help && mbrelay --help
/opt/mbtools/bin/python -c "import importlib.metadata as m; print(m.version('mbtools'))"None of the four programs has a --version flag.
The daemon runs as root and needs nothing extra. Local clients do
need USB access: mbserial, mbdeploy deploy/debug and mbrelay, run
by a normal user against a board plugged into this host. They open the
USB serial / CMSIS-DAP device themselves. (For a board on a peer, the peer's
root daemon does the I/O, so no local access is needed.)
sudo mbregistry install-service writes
/etc/udev/rules.d/99-mbregistry-cmsis-dap.rules. The file grants group
plugdev (mode 0660) and uaccess on the micro:bit's tty, raw-USB and
hidraw nodes (VID:PID 0d28:0204). Then:
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG plugdev "$USER" # then log in again: new SSH session
ls -l /dev/ttyACM* # crw-rw---- root plugdev
id | grep plugdevuaccess only helps a user logged in at a local seat. Over SSH, the
plugdev group is what works. If your distro has no plugdev, run
sudo groupadd plugdev first. Until access is set up, prefix local client
commands with sudo.
macOS and Windows need no equivalent step.