Skip to main content

Pybricks developer tools

Project description

Coverage Status Documentation Status

Pybricks tools & interface library

This is a package with tools for Pybricks developers. For regular users we recommend the Pybricks Code web IDE.

This package contains both command line tools and a library to call equivalent operations from within a Python script.


Python Runtime

pybricksdev requires Python 3.8 or higher.

Command Line Tool

We recommend using pipx to install pybricksdev as a command line tool.

We also highly recommend installing pipx using a package manager such as apt, brew, etc. as suggested in the official pipx installation instructions.

And don't forget to run pipx ensurepath after the initial installation. This will make it so that tools installed with pipx are in your PATH. You will need to restart any terminal windows for this to take effect. If that doesn't work, try logging out and logging back in.

Then use pipx to install pybricksdev:

# POSIX shell (Linux, macOS, Cygwin, etc)
PIPX_DEFAULT_PYTHON=python3.8 pipx install pybricksdev

Setting the PIPX_DEFAULT_PYTHON environment variable is only needed when pipx uses a different Python runtime other that Python 3.8. This may be the case if your package manager uses a different Python runtime.

Windows users

If you are using the Python Launcher for Windows (installed by default with the official Python installer), then you will need to use py -3.8 instead of python3.8.

py -3.8 -m pip install --upgrade pip # ensure pip is up to date first
py -3.8 -m pip install pipx
py -3.8 -m pipx ensurepath
py -3.8 -m pipx install pybricksdev

Linux USB

On Linux, udev rules are needed to allow access via USB. The pybricksdev command line tool contains a function to generate the required rules. Run the following:

pybricksdev udev | sudo tee /etc/udev/rules.d/99-pybricksdev.rules


To install pybricksdev as a library, we highly recommend using a virtual environment for your project. Our tool of choice for this is poetry:

poetry env use python3.8
poetry add pybricksdev

Of course you can always use pip as well:

pip install pybrickdev --pre

Using the Command Line Tool

The following are some examples of how to use the pybricksdev command line tool. For additional info, run pybricksdev --help.

Flashing Pybricks MicroPython firmware

Make sure the hub is off. Press and keep holding the hub button, and run:

pybricksdev flash <>

Replace <> with the actual path to the firmware archive.

You may release the button once the progress bar first appears.

The SPIKE Prime Hub and MINDSTORMS Robot Inventor Hub do not have a Bluetooth bootloader. It is recommended to install Pybricks using a Python script that runs on the hub. You can also flash the firmware manually using DFU.

Running Pybricks MicroPython programs

This compiles a MicroPython script and sends it to a hub with Pybricks firmware.

pybricksdev run --help

# ble connection examples:

# Run a one-liner on a Pybricks hub
pybricksdev run ble "print('Hello!'); print('world!');"

# Run script on the first device we find called Pybricks hub
pybricksdev run ble --name "Pybricks Hub" demo/

# Run script on device with address 90:84:2B:4A:2B:75 (doesn't work on Mac)
pybricksdev run ble --name 90:84:2B:4A:2B:75 demo/

# Other connection examples:

# Run script on ev3dev at
pybricksdev run ssh --name demo/

# Run script on primehub at
pybricksdev run usb --name "Pybricks Hub" demo/

Compiling Pybricks MicroPython programs without running

This can be used to compile programs. Instead of also running them as above, it just prints the output on the screen instead.

pybricksdev compile demo/

pybricksdev compile "print('Hello!'); print('world!');"

This is mainly intended for developers who want to quickly inspect the contents of the .mpy file. To get the actual file, just use mpy-cross directly. We have used this tool in the past to test bare minimum MicroPython ports that have neither a builtin compiler or any form of I/O yet. You can paste the generated const uint8_t script[] directly ito your C code.

Additional Documentation (work in progress)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pybricksdev, version 1.0.0a14
Filename, size File type Python version Upload date Hashes
Filename, size pybricksdev-1.0.0a14-py3-none-any.whl (197.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pybricksdev-1.0.0a14.tar.gz (191.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page