Installing & Configuring the Thonny IDE

Contents

What is MicroPython?

This website promotes MicroPython programming on a wide variety of inexpensive and generally available microcontroller boards. So it's apt to very briefly describe MicroPython, the easy to use but powerful programming language.

From the official website, micropython.org,  we learn MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimised to run on microcontrollers and in constrained environments.

It also includes MicroPython specific modules that allow direct access to hardware and peripherals commonly found on microcontrollers.

The MicroPython system is flashed to the microcontroller's flash memory. It runs "bare metal" i.e. does not require an underlying operating system. It consists of a core runtime which includes an interpreter and a runtime VM (virtual machine).

MicroPython source code scripts are flashed to the microcontroller. When the microcontroller is reset the interpreter converts the MicroPython source code into an intermediate format called bytecode. This bytecode is then executed by the VM.

What is Thonny?

MicroPython exists entirely on the microcontroller. It does not provide the tools to write the source code and flash it to the microcontroller's memory. Thus a separate specialist IDE (or toolchain) running on a computer is required.

Thonny provides this, all in one simple to use package. With respect to microcontrollers, Thonny is specifically for the development and deployment of MicroPython programs. It cannot be used to program a microcontroller with other languages eg. C or C++.

Additionally, Thonny is available as a remote IDE for writing and executing Python scripts on a single board computer such as a Raspberry Pi. In this case the computer that's running Thonny connects to the single board computer via SSH. Thonny does all the work maintaining this connection across the network.

Thonny can also be used as a handy IDE for writing and running Python programs on the local computer.

Thonny is easy to install. It's available for Windows, Mac and Linux. Visit the official website at thonny.org for further details including the install files.

Installing Thonny

Thonny is easy to install, especially for Windows. It is available for Windows, Mac and Linux. We will describe the Windows and Linux installs. At the time of writing (March 2026) the latest version was 4.1.7 (released December 16, 2024).

Windows Install

  1. Go to thonny.org and click the Windows link in the top-right corner. Select Installer with 64-bit Python 3.10 and download the thonny-4.1.7.exe install file.
  2. Run the downloaded .exe file and follow the prompts.
  3. After installation, open Thonny from the Start menu or desktop shortcut.

Linux Install

We use Fedora  but the following instructions should work for most Linux distributions.

It is important that the following instructions are used to install Thonny. Don't use a Package Manager because an older version of Thonny that won't open will probably be installed. This is a known issue.

The procedure given below uses the Linux install script on the Thonny site which ensures the correct version is installed.

  1. Open a terminal window (CTRL-ALT-T).
  2. Enter the following script:

    bash <(wget -O - https://thonny.org/installer-for-linux)
  3. Press ENTER.
  4. After the script has completed press ENTER to exit the installer. A Thonny shortcut should have been installed on the desktop.
  5. The user must be added to the dialout group to obtain permission to use the (USB) serial port. Enter the following in the terminal:

    sudo usermod -a -G dialout $USER
  6. Reboot the system.

Connecting the Microcontroller Board to Thonny

With Thonny installed on the computer the next step is to connect the microcontroller board to the computer. With a suitable cable connect the board's USB port to any USB port on the computer.

Windows: Verifying the Connection

On a Windows computer a successful connection can be verified through the Device Manager. It will appear as a USB Serial Device  under Ports (COM & LPT).


Device Manager view of the COM port used to connect the Pyboard to the computer.
Fig 1 - Serial port (COM4) connecting the microcontroller board

Additionally, a new drive will often appear in the computer's File Explorer. The drive is physically located in flash memory on the microcontroller board.

Linux: Verifying the Connection

There are several ways to check for a successful connection in Linux:

  • List USB devices with : Run  lsusb  in a terminal and look for an entry to the physical microcontroller. Our WeAct Black Pill (STM32F411) showed up as;

    MicroPython Pyboard Virtual Comm Port in FS Mode
  • Verify device file presence: Run  ls /dev/tty*  in a terminal and look for an entry of the form "/dev/ttyUSB*" or "/dev/ttyACM*".

    Our WeAct Black Pill (STM32F411) showed up as; /dev/ttyACM0

Selecting the Microcontroller Board in Thonny

Thonny will often successfully detect the microcontroller board if the program is started after the board has been plugged into the computer's USB port. Thonny detected our Black Pill and wrote the following to the REPL:

MicroPython v1.27.0 on 2025-12-09; WEACT_F411_BLACKPILL
with STM32F411CE
Type "help()" for more information.
>>> 
MicroPython v1.27.0 on 2025-12-09; WEACT_F411_BLACKPILL
with STM32F411CE

Type "help()" for more information.

>>>

If necessary the microcontroller board can be manually selected in Thonny. On the bottom right-hand side of the Thonny application window is a small hamburger menu icon. Click this and select the board from the options presented.

Thonny's Interpreter menu is used to connect the Black Pill to Thonny.
Fig 2 - Thonny's Interpreter menu, connecting the Black Pill to Thonny

Thonny File, REPL and Edit Panes

This step ensures that all the necessary panes within Thonny are visible.

  • Reveal the Files pane: This handy pane provides file manager style access to the local computer file system as well as the microcontroller board's file system.
  • Ensure the REPL is visible: The Read-Evaluate-Print Loop is an interactive environment that allows direct communication with the MicroPython interpreter running on a microcontroller board. Python commands can be directly entered here and immediately executed. It's also where MicroPython program output is directed.

Click the View  menu in Thonny and ensure that Files and Shell are selected.

The Files pane provides some very useful features. Double-clicking any file will load it into the source code editor. Right-clicking any file brings up a handy context sensitive menu that allows (amongst other things) to delete the file or copy it to the other device (computer or microcontroller board).

The pane labelled <untitled> in Fig 3 is the source code editor where MicroPython program code is entered. This pane is a tabbed view with each each tab representing a separate MicroPython (or Python) program. Click the left-most Toolbar icon to create another tab inside the Edit pane.

The pane labelled Shell is the REPL where Python commands can be directly entered and immediately run. Python program output from the print() function also appears here.

Use Thonny's View menu to display the Shell (REPL) and the files view.
Fig 3 - Thonny with File, Editor and REPL panels

Thonny's Menu & Toolbar

Thonny's main menu and toolbar.
Fig 4 - Thonny's main menu and toolbar

The first three buttons on the toolbar are the most used file commands: New  file, Open  file and Save  file.

The next button (green circle with a white arrow) when clicked will cause the MicroPython source code in the Editor to be flashed to the microcontroller board and run.

The greyed out buttons control the Thonny debugger. This is not available for MicroPython programs executed on an external microcontroller.

The button with the stop symbol will reset the microcontroller board if the REPL becomes locked.

Writing and Running a MicroPython Script

Connect your microcontroller board with MicroPython firmware to Thonny. Click the New  button on the Thonny toolbar. Enter (or copy) the following MicroPython program into the Thonny Editor pane:


# Returns the sum of a series of sequential integers:
# 1, 2, ..., limit                   
def sum(limit):
    sum = 0
    for i in range(1, limit + 1):
        sum += i
    return sum

# Sum the first 100,000 integers
count = 100000
print('Sum of first', count, 'integers:', sum(count))

Click the Run current script  button on the toolbar. The following should appear in the REPL:


>>> %Run -c $EDITOR_CONTENT

MPY: sync filesystems
MPY: soft reboot
Sum of first 100000 integers: 5000050000
>>>