MicroPython

This page describes MicroPython support since Thonny 3.2. See the bottom of the page for historical notes.

Preparation

Linux

Before being able to connect to your device via USB, you may need to add your user to the dialout group (more generally, to the group, which owns the port, eg /dev/ttyUSB0).

If you don't see the port after plugging in the device, then brltty may be interfering. If you don't need it, then simply sudo apt autoremove brltty.

Configuration

Before continuing, make sure that you have your device attached to a USB port. If required, install the necessary drivers for serial communication.

In Thonny, open the back-end manager (Run → Select interpreter) and choose the type of your device from the drop-down list. If your device doesn't have a specific back-end, then try "MicroPython (generic)". NB! Since version 3.3 you can also use the back-end switcher in the lower-right corner of Thonny's main window.

Now you can specify the port your device is connected to. If you have only one board connected, then you could leave this setting for automatic detection.

After you press "OK", Thonny's shell should present either the prompt of your device's REPL or the output of the script which is currently running on your device.

(If you don't have suitable MicroPython (or CircuitPython) firmware installed on your device yet, then see below for the section about firmware installation.)

Editing scripts

When you have a MicroPython back-end selected, "File => Open" allows you to open a file either from local disk, device's USB drive, or "directly" form your device's file system. Same goes to save commands ("Save", "Save as", "Save copy as").

Note that Thonny always synchronizes file writes — this reduces the risk of corrupt files when you accidentally reset your device without proper eject right after saving a file onto its USB drive.

You can also open files by double-clicking them in Thonny's file browser (View => Files).

During editing your scripts, Thonny offers autocomplete (performed by the jedi library). This is based on the API-s scraped from specific devices with specific MicroPython / CircuitPython versions (different for each backend type). This means that if you are using a different version of firmware then the autocompleter may offer some names that are not present on your device and miss some that are.

Although Thonny allows you to work without saving anything locally, for serious work we recommend keeping master copies of your scripts in your main computer (preferably under version control) and copy them to the device as required (File => Save copy as). It is too easy to lose your work if you rely only on the device's flash memory.

Running scripts

The easiest way to test your script is to execute it like you would with the CPython back-end — "Run → Run current script (F5)". It doesn't matter whether your script is stored on the local disk or on the device — in both ways Thonny simply submits the program text to device's REPL.

When you have saved your script onto the device (eg. as "main.py"), you can check how your device would perform without Thonny. This can be done easily by selecting "Run => Send EOF / Soft reboot (Ctrl+D)".

Managing other files

You can upload / download data and library files and directories via respective commands in the file browser (View => Files) via files' context menu (opened by right-clicking on a file).

Thonny REPL vs. plain MicroPython serial REPL

After connecting to your device, Thonny switches it to raw REPL mode and uses this mode under the hood to run the scripts, query global variables, etc. For the user it is still presented as regular REPL. (Note that this mode change is not permanent — if you reset the device and open it with another program, REPL is back in regular mode. If you don't want to reset it then you can get back to regular mode with Ctrl+B.)

Because of using raw REPL under the hood, Thonny doesn't support Ctrl-A and Ctrl-B for switching between raw and regular REPL. It also doesn't support Ctrl-E for entering paste mode -- this is not necessary as you can paste any amount of code into the regular Thonny REPL.

Firmware installation / upgrade

Some MicroPython back-ends offer support for installing MicroPython to your device. In this case the back-end configuration page (Run => Select interpreter) has a button for this.

Time Synchronization

Thonny will automatically sync the RTC (Real Time Clock) on your board with your local time on connection. If you'd like to disable this, see the sync_time configuration option below. If this is supported for your board, calling utime.time() will give you the correct time automatically.

Until version 3.3.3 RTC was synced to UTC. Since 3.3.4 it is synced to local time by default, but you can choose UTC by setting utc_clock to True.

Advanced configuration

There are some hidden configuration options, which most of the users don't need to tweak, but which may be useful in some cases. In order to change them, you need to find the location of configuration.ini (Tools => Open Thonny data folder), close Thonny and edit the file by hand.

Here is an example section for ESP32 back-end:

[ESP32]
submit_mode = raw
write_block_size = 255
write_block_delay = 0.03
sync_time = True
utc_clock = False

• submit_mode controls how code is sent to the board. Thonny 3.2 sent it via raw mode, Thonny 3.3.0 and 3.3.1 via paste mode and since 3.3.2 the default is raw_paste if the device supports it (a new mode appearing in MicroPython 1.14) or raw as fallback. Some devices are supposed to support raw_paste, but get stuck for some reason -- in this case it's worth trying the original paste mode. (Note, that some devices have problems with paste mode, see https://github.com/thonny/thonny/issues/1461 for an example.)
• write_block_size and write_block_delay control how the code is submitted in raw mode and for submitting data to stdin (write_block_size is also used with paste mode). Thonny will break the data into blocks of write_block_size and waits write_block_delay seconds after writing each block. You may need to lower write_block_size and/or increase write_block_delay Thonny is having trouble with communicating with your device. Different back-ends have different defaults for these options (0.01 suffices for many boards, but 0.5 may be required for WebREPL connection on ESP32.)
• sync_time = True (default) makes Thonny to update device's real time clock (RTC) after connecting. You may want to turn it off when you are using another means for updating RTC (eg. NTP) or when you don't care and want connecting to be as fast as possible
• utc_clock = False means device's RTC gets synchronized to (or is assumed to keep) local time (default since Thonny 3.3.4). utc_clock = True would use UTC instead (default until 3.3.3). File browser will adapt to either setting and shows modification times in local time.

The section identifiers for different back-ends are ESP32, ESP8266, GenericMicroPython, CircuitPython, microbit, RP2040, RPiPico. If the section doesn't exist yet, then add it, but make sure you don't end up with several sections with same identifier (Thonny won't start then). If you mess up the configuration file, then you may delete it and Thonny will start with default options.

History

• MicroPython support in Thonny started with BBC micro:bit plug-in by Kauri Raba.
• General MicroPython support appeared in Thonny 3.0 and was meant to be used via separate plug-ins.
• Initially one had to edit scripts as local files and save them to the device with special commands in "Device" menu (as described here).
• Thonny 3.2 introduced device file browser and allowed to edit files directly in device's file system. "Device" menu was deprecated as file handling commands moved to file browser and firmware commands moved to respective back-end configuration pages. Upload commands are substituted with "File => Save as" and "File => Save copy as" commands.
• Thonny 3.2 incorporated several plug-ins (microbit, circuitpython, esp) into the main "thonny" package.