Getting Started with Thonny MicroPython (Python) IDE for ESP32 and ESP8266

If you want to program your ESP32 and ESP8266 with MicroPython firmware, it’s very handy to use an IDE. In this guide, we’ll introduce you to Thonny IDE. After completing this guide, you’ll have your first LED blinking using MicroPython and Thonny IDE.

We’ve experimented with several IDEs to program the ESP32 and ESP8266 boards using MicroPython, and Thonny seemed a good choice. Although there are some bugs, it is constantly being updated and improved.

It allows you to program your ESP32 and ESP8266 boards with MicroPython, and it is compatible with Windows, Mac OS X, and Linux. It even comes installed by default on the Raspberry Pi OS. Additionally, it’s easy to install, so you shouldn’t have problems with the installation process.

Alternatively, you may want to check the following compilation of MicroPython-compatible IDEs:

What is MicroPython?

MicroPython Logo

MicroPython is a Python 3 programming language re-implementation targeted for microcontrollers and embedded systems. MicroPython is very similar to regular Python. Apart from a few exceptions, the language features of Python are also available in MicroPython. The most significant difference between Python and MicroPython is that MicroPython was designed to work under constrained conditions.

Because of that, MicroPython does not come with the entire pack of standard libraries. It only includes a small subset of the Python standard libraries, but it includes modules to easily control and interact with the GPIOs, use Wi-Fi, and other communication protocols.

Installing Thonny IDE

In this guide, we provide instructions to install Thonny IDE in different operating systems, read the section that fits your needs:

Tip: Thonny IDE comes installed by default on Raspbian OS that is used with the Raspberry Pi board.

A) Installing Thonny IDE – Windows PC

To install Thonny on your Windows PC, follow the next instructions:

1. Go to https://thonny.org

2. Download the version for Windows and wait a few seconds while it downloads.

thony-ide-micropython-windows

3. Run the .exe file.

4. Follow the installation wizard to complete the installation process. You just need to click “Next”.

5. After completing the installation, open Thonny IDE. A window as shown in the following figure should open.

thony-ide-micropython-windows

B) Installing Thonny IDE – Mac OS X

Since Thonny IDE is open source and downloaded from the Internet, it’s not a verified app in the App Store. For security reasons, Mac OS X blocks unknown apps to run on your computer. Follow these next instructions to enable any downloaded software to run in your Mac.

1. Open the “System Preferences...” menu.

2. Open the “Security & Privacy” menu.

3. At the bottom left corner, click the lock icon to modify your “Security & Privacy” settings:

4. Type your username/password and click the “Unlock” button.

5. Finally, select the option “Allow apps downloaded from: Anywhere“.

That’s it, you can close that window.

To install Thonny on Mac OS X, follow the next instructions:

1. Go to https://thonny.org

2. Download the version for Mac OS X and wait a few seconds while it downloads.

3. Open the .dmg file.

4. Drag the “Thonny” application to your Desktop:

5. Thonny IDE is now installed and you can double-click to open it:

6. After the installation is completed, open Thonny IDE. A window as shown in the following figure should open.

C) Installing Thonny IDE – Linux

To install Thonny on your Linux computer, it depends on your Linux distribution and version, follow the next instructions for your system. First, we recommend installing these dependencies: python3, python3-pip, and python3-tk

If you’re in Ubuntu, you can install the Python dependencies like this:

sudo apt install python3 python3-pip python3-tk

After having Python3, pip3, and Python3 Tkinter, you can install Thonny IDE.

  • Ubuntu (after running that command, you’ll need to press Enter again to install the software):
bash <(wget -O - https://thonny.org/installer-for-linux)
  • Or you can install Thonny IDE with pip3:
sudo pip3 install thonny
  • Fedora since 27:
sudo dnf install thonny
  • Raspbian since Stretch (installed by default):
sudo apt install python3-thonny

After installing Thonny IDE and depending on your installation method, to open Thonny IDE:

  • You either need go to the search bar and type “Thonny” to find it
  • Or if you installed Thonny IDE using pip3, you can type in your terminal window:
thonny

Then, it should open Thonny IDE:

Flashing MicroPython Software

MicroPython isn’t flashed onto the ESP32 or ESP8266 boards by default. The first thing you need to do to start programming your boards with MicroPython is flash/upload/burn the firmware.

There are different ways in which you can do that. Thonny IDE comes with a tool that allows you to quickly install MicroPython firmware on your board. Another method is using esptool—check this tutorial to burn MicroPython firmware with esptool.py if you have trouble flashing the firmware with Thonny IDE.

Downloading MicroPython Firmware

Go to the MicroPython Downloads page: https://micropython.org/download/.

Select the type of board you’re using. Here are the quick links for “regular” ESP32 and ESP8266 boards:

You should see a similar web page (see figure below) with links to download .bin files. Download the latest release.

Download MicroPython Firmware

At the time of writing this article, the latest release is v1.17 (2021-09-02).bin for the ESP32 and ESP8266 boards. Don’t download the Nightly builds; those versions are not stable and are only recommended for advanced programmers.

The downloaded file will probably go to the Downloads folder. Continue reading to learn how to flash the firmware on your boards.

Flashing MicroPython Firmware using Thonny IDE

In this section, you’ll learn how to flash MicroPython firmware on your boards using Thonny IDE. Follow the next steps:

1) Connect your ESP32 or ESP8266 board to your computer.

2) Open Thonny IDE. Go to Tools > Options > Interpreter.

3) Select the interpreter you want to use accordingly to the board you’re using and select the COM port your board is connected to. Finally, click on the link Install or update firmware.

Flash MicroPython Firmware Thonny IDE

4) Select the port once again, and then click on the Browse button to open the .bin file with the firmware you’ve downloaded on the previous step. Select the options as shown in the picture below and finally click on Install.

ESP Firmware Flasher Thonny IDE

After a few seconds, the installation should be completed.

Testing the Installation

Important: before testing the installation, your ESP32/ESP8266 board needs to be flashed with MicroPython firmware (see the previous step).

Connect the board to your computer using a USB cable. To test the installation, you need to tell Thonny that you want to run MicroPython Interpreter and select the board you are using.

1. Go to Tools > Options and select the Interpreter tab. Make sure you’ve selected the right interpreter for your board as well as the COM port.

You can also select the “Try to detect automatically” option, but only if you just have one board connected to your computer at a time. Otherwise, select the specific port for the board you’re using.

2. Thonny IDE should now be connected to your board and you should see the prompt on the Shell.

3. Type the command help() in the Shell and see if it responds back.

If it responded back, everything is working fine. Now, you can send a few more commands to test.

Send the following commands to light up the on-board LED

>>> from machine import Pin
>>> Pin(2, Pin.OUT).value(1)

If you’re using an ESP8266, the logic to turn on the LED works the other way around, so you should send the following command instead:

>>> Pin(2, Pin.OUT).value(0)

The on-board LED should light up.

ESP32 board Built in LED turned on HIGH

Then, turn off the led like this for the ESP32:

>>> Pin(2, Pin.OUT).value(0)

And like this for the ESP8266:

>>> Pin(2, Pin.OUT).value(1)

Congratulations! Your installation was successful!

Thonny IDE Overview

At this point, you should have:

  • Thonny IDE installed on your computer
  • ESP32/ESP8266 flashed with MicroPython firmware

Open Thonny IDE. There are two different sections: the Editor and the MicroPython Shell/Terminal:

  • The Editor section is where you write your code and edit your .py files. You can open more than one file, and the Editor will open a new tab for each file.
  • On the MicroPython Shell you can type commands to be executed immediately by your ESP board without the need to upload new files. The terminal also provides information about the state of an executing program, shows errors related with upload, syntax errors, prints messages, etc…

You can also customize Thonny IDE to show other useful tabs. Go to View and you can select several tabs that provide more information.

Something that could be very useful is the Variables tab. It lists all available variables in your program and their corresponding values.

Running Your First Script

To get you familiar with the process of writing a file and executing code on your ESP32/ESP8266 boards, we’ll upload a new script that simply blinks the on-board LED of your ESP32 or ESP8266.

Creating the main.py file on your board

1. When you open Thonny IDE for the first time, the Editor shows an untitled file. Save that file as main.py by clicking on the save icon. Select the “This computer” option. We recommend saving the file inside a folder with a name that identifies the project, for example Blink. The file must be called main.py. Otherwise, it will not work.

2. The Editor should now have a tab called main.py.

3. Copy the following code to the main.py file:

from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
  led.value(not led.value())
  sleep(0.5)

Uploading the Script

1) Go to File > Save as… or click on the save icon. The following window will open.

Thonny IDE Save to MicroPython Device

2) Select MicroPython device.

3) Name the file main.py, otherwise, it won’t work. Notice that the window that pops up shows the files currently saved on the board filesystem. There should be a file called boot.py. That file is created by default when you burn MicroPython firmware.

Thonny IDE Save main.py File

4) Finally, click Ok to proceed.

5) Now, press the on-board RST/EN button so that the board restarts and starts running the code.

6) Now, your board should be blinking the blue on-board LED every 500 milliseconds.

The following figure shows the ESP32 on-board LED light up.

ESP32 board Built in LED turned on HIGH

And the following figure shows the ESP8266.

Troubleshooting Tips for Thonny IDE

We’ve discovered some common problems and error messages that occur with Thonny IDE. Usually restarting your ESP with the on-board EN/RST button fixes your problem. Or press the Thonny IDE “Stop/Restart backend” button and repeat your desired action. In case it doesn’t work for you, read these next common errors and discover how to solve them.

Error #1: You get one of the following messages:

========================= RESTART =========================
Unable to connect to COM4
Error: could not open port 'COM4': FileNotFoundError(2, 'The system cannot find the file specified.', None, 2)

Check the configuration, select Run → Stop/Restart or press Ctrl+F2 to try again. (On some occasions it helps to wait before trying again.)

Or:

========================= RESTART =========================
Could not connect to REPL.
Make sure your device has suitable firmware and is not in bootloader mode!
Disconnecting.

Or:

========================= RESTART =========================
Lost connection to the device (EOF).

Unplug, and plug back your ESP board. Then, double-check that you’ve selected the right serial port in the Tools > Options > Interpreter > Port. Then, click the “Stop/Restart backend” button to establish a serial communication. You should now be able to upload a new script or re-run new code.

These errors might also mean that you have your serial port being used in another program (like a serial terminal or in the Arduino IDE). Double-check that you’ve closed all the programs that might be establishing a serial communication with your ESP board. Then, unplug and plug back your ESP board. Finally, restart Thonny IDE.

Error #2: Thonny IDE fails to respond or gives an Internal Error:

When this happens, you can usually close that window and it will continue to work. If it keeps crashing, we recommend restarting the Thonny IDE software.

Error #3: Thonny IDE hangs when pressing “Stop/Restart backend” button:

When you press the “Stop/Restart backend” button, you need to wait a few seconds. The ESP needs time to restart and establish the serial communication with Thonny IDE. If you press the “Stop” button multiple times or if you press the button very quickly, the ESP will not have enough time to restart properly and it’s very likely to crash Thonny IDE.

Error #4: Problem restarting your ESP board, running a new script, or opening the serial port:

Brownout detector was triggered

Or if the ESP keeps restarting and printing the ESP boot information:

ets Jun 8 2016 00:22:57 

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) 
configsip: 0, SPIWP:0xee 
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 
mode:DIO, clock div:2 
load:0x3fff0018,len:4 
load:0x3fff001c,len:4732 
load:0x40078000,len:7496 
load:0x40080400,len:5512

The “Brownout detector was triggered” error message or constant reboots means that there’s some sort of hardware problem. It’s often related to one of the following issues:

  • Poor quality USB cable;
  • USB cable is too long;
  • Board with some defect (bad solder joints);
  • Bad computer USB port;
  • Or not enough power provided by the computer USB port.

Solution: try a different shorter USB cable (with data wires), try a different computer USB port or use a USB hub with an external power supply.

Important: if you keep having constant problems or weird error messages, we recommend re-flashing your ESP board with the latest version of MicroPython firmware.

Error #5: When I try to establish a serial communication with the ESP32/ESP8266 in Thonny IDE, I can’t get it to connect.

We think this is what’s happening: when you’re running a script in your board, sometimes it’s busy running that script and performing the tasks.

So, you need to try start the connection by pressing “Stop/Restart backend” button multiple times or restart the ESP to catch available to establish the serial communication.

Warning: don’t press the “Stop/Restart backend” button multiple times very quickly. After pressing that button, you need to be patient and wait a few seconds for the command to run.

If you’re running a script that uses Wi-Fi, deep sleep, or it’s doing multiple tasks, I recommend trying 3 or 4 times to establish the communication. If you can’t, I recommend re-flash the ESP with MicroPython firmware.

Error #6: debug tools are grayed out:

Thonny IDE debug tools aren’t available for MicroPython. The debug tools are only available for the Python Interpreter, so being grayed out is the expected behavior.

Wrapping Up

Thonny IDE is a great IDE to program the ESP32 and ESP8266 boards using MicroPython. It is compatible with Windows, Mac OS X, and Linux and it is easy to install.

We have an article with a compilation of several MicroPython IDEs compatible with the ESP32 and ESP8266 boards that you can check below:

More tutorials about MicroPython with ESP32 and ESP8266:

Learn more about MicroPython with our eBook:

Thanks for reading.



Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »
Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »

Enjoyed this project? Stay updated by subscribing our newsletter!

36 thoughts on “Getting Started with Thonny MicroPython (Python) IDE for ESP32 and ESP8266”

  1. Thonny 3.1.2 – The run current script button (the green circle with ‘play’ symbol) works instead of having to “upload current script as main script” and then having to reset the board.

    Reply
  2. Hello ! The function >>> %lsdevice doesn’t work on Thonny installed on RaspBian, but it works on my MacOS. Do you know what’s the problem ?

    Reply
    • Hi Vincent.
      I’m sorry but I don’t know why that happens.
      I use Thonny IDE on windows.
      Make sure your Thonny IDE is configured properly to use micropython and not Python.
      Regards,
      Sara

      Reply
  3. Python 38 on Windows 10
    Thonny 3.27 in Python
    MicroPython 1.12

    It seems to be a big difference against the versions are used in your tutorial:
    %lsdevice >>> not working
    %cat /main.py >>> not working
    Device doesn’t show “commands”

    Reply
  4. Hi Sara, help me please.
    I’m using the Thonny IDE in Raspbian. I can connect to ESP32 and run the script. But when I try to upload the “main.py” script on ESP32 by clicking on “device” the option “Upload current script as main script” does not exist. When I click on “device” appears “Where are all the commands?” And the following message appears: “MicroPython commands have been moved or replaced:”
    Can you help me?

    Reply
    • Hi Bruno.
      That happens on the most recent versions of Thonny.
      You need to go to File > Save Copy and then select MicroPython device.
      Give the file a name, in this case main.py and then save it.
      I hope this helps.
      Regards,
      Sara

      Reply
  5. I am using pyboard micropython V1.1
    Can’t get it to recognize Ctrl-E or any of the other REPL commands.
    Also, fails with sys.stdin.read(1)

    Reply
      • Yes. But after reading about and experimenting with Thonny, it’s really designed for ESP32. It’s not suited for STM32.
        Frustrating to me is that another IDE, Mu, is the same–ideal for ESP32 or CircuitPython, but not for any MicroPython running on a STM32. I’m an EE with 45 years of experience. I’ve used MicroPython on ESP32, STM32, and CircuitPython on ATSAM’s. Of all of them, only the STM32 with MicroPython is adequate for industrial use because of advanced professional features such as: interrupt handling, embedded assembly code, direct register addressing, asyncio task scheduling, and industrial/automotive rated hardware. The others are GREAT for teaching and learning programming and basic hardware interfacing. And Thonny is wonderful to use with my ESP32 boards.

        Reply
        • I’m sorry about that.
          We don’t have any tutorials about the Pyboard.
          I haven’t experimented with that board, so I can’t recommend any particular IDE.
          Have you experimented, for example: PyCharm with MicroPython plugin or VSCode with MicroPython Plugin?
          Regards,
          Sara

          Reply
          • Tried them all. Hundreds of megabytes of disk space just to edit software? Still have to copy and paste into the REPL or manually save the file to Flash. PyCraft is probably the best so far, but it can cause exception errors and a Windows “blue screen of death”. And it’s interface could use some work. Notpad++ has a plug-in as well. Seems stable.

  6. Hi Sara,

    Since a year I am following your great tutorials and, of course I am doing hand-ons myself.
    I have an 4MB ESP32 board, flashed MicroPython firmware on it, using esptool and started Thonny IDE to do some programming. It connects to my board, I can read the default boot.py contents, but the main.py (%cat main.py) stucks in an error (Error 21 EISDIR). I cannot upload even the most simple .py program, whatever I try. Typing the python program manually into REPL terminal makes it run however. I tried some micropython firmware versions, but all have the same problem. The .bin file used in your Micropython course version 1.2 is not available on the internet. There is only generic ESP32 firmware. I am working on debian 10 linux and have Python 3.8 installed.
    What can I do to start programming?
    Thanks,

    Reply
    • Thanks for the info Aivar, I was searching from a long time that why device menu is not available for me only. But I have two problems the one is %lsdevice or %cat /main.py is not working with me.
      The second is when I upload a forever loop program to my esp32 there is no way to stop or overwrite with a new program. Any advice ?

      Thanks.
      Nadeem

      Reply
      • %lsdevice and %cat are also gone, because the file browser (View => Files) and the ability to load files from the device have taken their place.

        Can’t you stop your loop program with Ctrl+C?

        Reply
  7. Good evening. I have followed all the steps of the book and the tutorial but I often get this error in the shell when I try to connect my esp32 CAM IA Thinker to my computer:

    Device is busy or does not respond. Your options:

    wait until it completes current work;
    use Ctrl + C to interrupt current work;
    use Stop / Restart to interrupt more and enter REPL.

    do you have any solutions for me please?

    Reply
    • Hi.
      Check that your board is not running any code (click the STOP button on the IDE) and that it is not being used in another program (like Arduino IDE for example).
      Regards,
      Sara

      Reply
  8. hi Sara, i need to know how to connect the device each time i open thonny fresh. as now it does not recognise automatically. i need to close the application and open it again then it is functioning.

    can you please tell me a remedy for this please. as if how to connect the device after opening the application each time.

    Reply
  9. Hello

    I have a ESP8266 NodeMCU which I have been using with Arduino Sketches. I want to run micropython on it, but Thoony will not connect as it says the device is busy. No can I connect with say esptool.py –port 7 erase_flash, as it reports could not open port. Port 7 is the port recognised by the IDE. I uploaded an empty sketch so usb port is not being used but no difference. Is there a solution or do you have to use a new device i.e. not run a sketch before

    Reply
  10. Hello. After more than a year’s pause, I’m going back to the “miracles” of electronics, so repeat everything, because my head is already worthy of “leaky.” But there are amazing Sara and Rui here, and that’s a certainty. Thank you and a lot of health.

    Reply
  11. Hi. I have a T-Pico C3 device, equipped with a dual core RP2040 and an ESP32C3 single core. The device is described here : https://github.com/Xinyuan-LilyGO/T-PicoC3
    I have no problem with the RP2040 part, but I can’t flash the micropython firmware using Thonny. On windows 10, when I connect the card (with the USB cable correctly plugged, I have the green led on, meaning it’s the ESP32 part) I can see the ESP32 in the device manager (port 13), but when I launch the flash with Thonny, I get an erro message: “Unable to connect to COM13: Cannot configure port, something went wrong. Original message: PermissionError(13, ‘Un périphérique attaché au système ne fonctionne pas correctement.’, None, 31). If you have serial connection to the device from another program, then disconnect it there first. Process ended with exit code 1.”
    It seems that the ESP32 is not recognized by the system, although the RP2040 is. Does anyone know how to fix this?

    Reply
  12. Is it possible (or do you have a tutorial) to put a NodeMCU/ESP8266 back to “factory defaults”?
    i.e. I have flashed MicroPython but am no longer needing it.
    How can I get back to a point where I can load “regular” ESP8266 programs?
    I have been enjoying learning from your great tutorials!

    Reply
  13. How do you get
    the firmware modal to install :”4) Select the port once again, and then click on the Browse button to open the .bin”
    I can’t get it from the interpreter tab ,after I install the preceding one with erasing the firmware
    but no modal to browse and enter the firmware is coming up

    Reply

Leave a Comment

Download Our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.