# Using the OPEN INSTALLER Button on circuitpython.org ## Overview ![OPEN INSTALLER button on circuitpython.org](https://cdn-learn.adafruit.com/assets/assets/000/138/783/medium800/circuitpython_open-installer-full.png?1754419155 ) Getting a bootloader and CircuitPython onto an Espressif board can be a complicated process, involving multiple downloads and software tools. But there's an easier way. The Espressif boards on the [board download pages on circuitpython.org](https://circuitpython.org/downloads) provide a button labelled **OPEN INSTALLER**. Clicking this button invokes the [Web Firmware Installer](https://github.com/adafruit/web-firmware-installer-js). This easy-to-use step-by-step tool can: - Erase the flash on a board - Install the TinyUF2 bootloader (if the board supports it) - Install CircuitPython - Fill in **settings.toml** with your desired network settings This Learn Guide describes how to the use the tool. Go to the page that describes which board you have: - [Boards with Full USB Support](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support): Espressif ESP32-S2, ESP32-S3 - [Serial-Only Boards](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/serial-only-boards): Espressif ESP32, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2   # Using the OPEN INSTALLER Button on circuitpython.org ## Boards with Full USB Support Info: This page is for boards with full USB support that can present as a disk drive and can use TinyUF2. This includes Espressif ESP32-S2, ESP32-S3, and ESP32-P4. For boards that only present a serial device, like ESP32, ESP32-C3, and ESP32-C6, see [Serial-Only Boards](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/serial-only-boards). ![OPEN INSTALLER button on circuitpython.org](https://cdn-learn.adafruit.com/assets/assets/000/138/773/medium800/circuitpython_open-install-bin-uf2.png?1754411152 ) Some of the [board download pages on circuitpython.org](https://circuitpython.org/downloads) provide a button labelled OPEN INSTALLER. Clicking this button invokes the [Web Firmware Installer](https://github.com/adafruit/web-firmware-installer-js). With this guided tool, on boards with full USB support, you can: - Erase the flash on a board - Install the TinyUF2 bootloader (if the board supports it) - Install CircuitPython - Fill in **settings.toml** with your desired network settings. You can skip some or all of these steps, as needed. Currently, the **OPEN INSTALLER** button is only present on the download pages for Espressif boards, but it may be added to other types of boards in the future. ## Opening Dialog To use the Web Firmware installer, first go to [https://circuitpython.org/downloads](https://circuitpython.org/downloads), find the entry for your board, and click on it. You will go to the download page for your particular board. There will probably be two **OPEN INSTALLER** buttons on the page, one for the current stable version of CircuitPython, and one for the latest development release. Choose the one you want to use. When you click **OPEN INSTALLER** , you will first see the dialog box below. The name of the board mentioned in the first paragraph will match the board name for the page you are on. Read the text if you haven't before, and then click **Next**. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/714/medium800/circuitpython_web-firmware-installer-1.png?1754338825 ) ## Installer Menu The next dialog box you see will give you a menu of choices. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/715/medium800/circuitpython_web--firmware-installer-menu-uf2.png?1754338895 ) - A  **Full CircuitPython Install**  will install the TinyUF2 bootloader, and then install CircuitPython using a UF2 file. Finally you will then be asked to supply WiFi credentials, which will be written to  **settings.toml**. - **Install CircuitPython UF2 only**  assumes TinyUF2 is already installed on the board. It will install CircuitPython by copying a UF2 to the BOOT drive. The WiFi credentials step is skipped. - **Install CircuitPython BIN**  only will install CIrcuitPython using a BIN file. If TinyUF2 is present, _ **it will be erased** _. The WiFi credentials step is skipped. - **Install Bootloader Only**  just installs TinyUF2. - **Update WiFi credentials**  assumes CircuitPython is already installed. It will write the WiFi credentials you enter to  **settings.toml**. Danger: CircuitPython 10 *requires* an update to TinyUF2 on boards with 4MB flash. So do a **Full Install**. You only need to do this once. We recommend everyone update TinyUF2 when updating to CIrcuitPython 10. This page will describe the **Full CircuitPython Install** , as shown below. See [Advanced: Install CircuitPython as a BIN file](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/advanced-install-circuitpython-as-a-bin-file) and [Advanced: Install TinyUF2 Bootloader Only](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/advanced-install-tinyuf2-bootloader-only) if you want to do something else. ![Full CircuitPython Install](https://cdn-learn.adafruit.com/assets/assets/000/138/789/medium800/circuitpython_web-firmware-installer-menu-uf2-full.png?1754423947 ) ## Connect to Your Board The next dialog box you see will be the one below. Follow the instructions to connect your board to your computer with a data-capable USB cable, and then put the board into ROM bootloader mode. It is easier to identify the right serial port if you disconnect any other boards or other serial devices. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/717/medium800/circuitpython_web-firmware-installer-serial-connect.png?1754338990 ) When you click the **Connect** button, a dialog box will appear for you to select the serial port. The images below show how this dialog box appears on Windows, macOS, and Linux. Choose the serial port (step 1 in the screenshots), and then click  **Connect** or **Select Folder** (step 2). - On Windows, the serial port will be `COMnn`. - On Linux, the serial port will usually be something like `/dev/ttyACMn`, `/dev/ttyAMAn`, or `/dev/ttyUSBn`.  - On macOS, the serial port will be `cu.something`. ![connect to serial port](https://cdn-learn.adafruit.com/assets/assets/000/138/751/medium800/circuitpython_web-firmware-installer-serial-connect-all.png?1754404694 ) ## Erase Flash The next dialog box after **Connect to Your Board** will ask if you want to erase the flash on your board. In general, don't click **Skip Erase** , but you can if you are sure you want to preserve the parts of flash that won't get overwritten. For instance, if you installing a new CircuitPython .bin file, or a new TinyUF2 bootloader, then the CIRCUITPY part of the flash may not be damaged by the flashing. But you can't necessarily depend on that, because the flash partition layout may have changed. So back up CIRCUITPY before you flash firmware. Danger: Installing firmware can erase the data you have stored on the board in CIRCUITPY. Using **Erase Flash** definitely will! Back up your data before proceeding. ![Erase Flash](https://cdn-learn.adafruit.com/assets/assets/000/138/718/medium800/circuitpython_web-firmware-installer-erase.png?1754339154 ) If you choose to erase the flash, you'll see this spinning for a bit: ![spinning "erasing" indicator](https://cdn-learn.adafruit.com/assets/assets/000/138/719/medium800/circuitpython_web-firmware-installer-erasing.png?1754339182 ) ## TinyUF2 Installation If you have chosen **Full install CircuitPython **  or  **Install Bootloader Only** , the next box you see will be the one below one, which is reporting that is has downloaded the **.zip** file for the bootloader, extracted a **.bin** file, and is now flashing it. Once the TinyUF2 bootloader finishes being flashed, the board will _stay_ in ROM bootloader mode. You'll need to press the RESET button to get TinyUF2 to start. ![TinyUF2 installation](https://cdn-learn.adafruit.com/assets/assets/000/138/721/medium800/circuitpython_web-firmware-installer-tinyuf2-install.png?1754339418 ) Info: Press the RESET button after flashing TinyUF2 to exit the ROM bootloader and start the TinyUF2 bootloader. ## CircuitPython UF2 Installation If you have chosen **Full CircuitPython Install** or **Install CIrcuitPython UF2** only, you will next see this box. As mentioned above, you'll need to reset your board first if you just installed TinyUF2. Otherwise double-click the RESET button to start the existing TinyUF2 bootloader. The, click the **Select [...]BOOT Drive** button. The exact name of the BOOT drive will vary based on the board. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/723/medium800/web-firmware-installer-circuitpython-uf2.png?1754339528 ) A dialog box will appear to let you select the BOOT drive. The images below show how this dialog box appears on Windows, macOS, and Linux. Choose the drive (step 1 in the screenshots), and then click **Select** or **Select Folder** (step 2), depending on your operating system. ![select BOOT drive](https://cdn-learn.adafruit.com/assets/assets/000/138/744/medium800/circuitpython_web-firmware-installer-select-boot-drive-all.png?1754400030 ) Before the installer can copy the CircuitPython UF2 to the BOOT drive, you must give it permission. You'll see a pop-up request like this one. Click  **Edit Files** or whatever the browser asks. ![Permit edit of BOOT drive](https://cdn-learn.adafruit.com/assets/assets/000/138/670/medium800/circuitpython_web-firmware-installer-boot-permission.png?1754268940 ) Warning: On Windows, the installer will complain that the drive name does not match the expected BOOT file name, as shown below. This is not an error. Simply click OK and proceed. ![Windows not expected drive name](https://cdn-learn.adafruit.com/assets/assets/000/138/828/medium800/circuitpython_web-firmware-installer-boot-drive-no-match-windows.png?1754505132 ) Then the installer will copy the CircuitPython UF2 for your board to the BOOT drive. ![Copy CircuitPython UF2 to BOOT drive](https://cdn-learn.adafruit.com/assets/assets/000/138/730/medium800/web-firmware-installer-copy-circuitpython-uf2.png?1754341994 ) Danger: WARNING: There is a [bug](https://github.com/adafruit/web-firmware-installer-js/issues/15) you may see using macOS that makes it appear as if the UF2 file copy has stalled near the end. The copy has in fact finished, but the installer cannot tell. You can start **OPEN INSTALLER** again and finish your installation by selecting **Update Wifi credentials**. ## Fill in **settings.toml** Finally, the last step is to specify network settings. First, the installer will ask you to select the CIRCUITPY drive so it can find and write the **settings.toml** file. Click the **Select CIRCUITPY Drive** button and choose the CIRCUITPY drive in the selection dialog box. ![select CIRCUITPY drive dialog box](https://cdn-learn.adafruit.com/assets/assets/000/138/728/medium800/circuitpython_web-firmware-installer-select-circuitpy-drive.png?1754341909 ) A dialog box will appear to let you select the CIRCUITPY drive. The images below show how this dialog box appears on Windows, macOS, and Linux. Choose the drive (step 1 in the screenshots), and then click **Select** or **Select Folder** (step 2), depending on your operating system. ![Windows, Linux, and macOS select CIRCUITPY](https://cdn-learn.adafruit.com/assets/assets/000/138/741/medium800/circuitpython_web-firmware-installer-select-circuitpy-all.png?1754399860 ) You will need to confirm that the installer is allowed to write to CIRCUITPY. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/726/medium800/circuitpython_web-firmware-installer-circuitpy-permission.png?1754341433 ) Then the installer will display a dialog box so you can enter the network settings. When you click **Next** , it will write those settings to the **settings.toml** file on CIRCUITPY. If you don't want to fill in these values now, just close the box, or leave the values blank and click **Next**. ![Fill in settings.toml](https://cdn-learn.adafruit.com/assets/assets/000/138/725/medium800/circuitpython_web-firmware-installer-settings-toml.png?1754341393 ) ## Done! Now you're all done! ![](https://cdn-learn.adafruit.com/assets/assets/000/138/724/medium800/circuitpython_web-firmware-installer-done.png?1754341368 ) # Using the OPEN INSTALLER Button on circuitpython.org ## Advanced: Install CircuitPython as a BIN file On boards that have full USB support, you can still choose to install CircuitPython as a **.bin** file. This is will skip the TinyUF2 installation,. Note that if you do that,  **you will overwrite TinyUF2** if it is on the board, and it will no longer be available until you install it again. Choose  **Install CircuitPython Bin Only** from the installer menu dialog box. ![install CircuitPython BIN file](https://cdn-learn.adafruit.com/assets/assets/000/138/784/medium800/circuitpython_web-firmware-installer-menu-uf2-bin-only.png?1754422275 ) You will see the dialog boxes for making a serial connection and erasing flash, as described on the [Boards With Full USB Support page](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support). First you'll see [Connect to Your Board](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support) (click for details) and you'll select the serial port. ![connect to serial port](https://cdn-learn.adafruit.com/assets/assets/000/138/787/medium800/circuitpython_web-firmware-installer-serial-connect.png?1754423080 ) Next you'll see the [Erase Flash](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support) box (click for more details). In general, don't skip erasing the board. ![Erase Flash](https://cdn-learn.adafruit.com/assets/assets/000/138/786/medium800/circuitpython_web-firmware-installer-erase.png?1754422955 ) Finally you'll see this **Flashing ...** box, showing that the installer is flashing the CircuitPython **.bin** file to the board. When it finishes, you'll be done. ![flash CircuitPython BIN file](https://cdn-learn.adafruit.com/assets/assets/000/138/785/medium800/web-firmware-installer-flash-circuitpython-bin-s2.png?1754422877 ) # Using the OPEN INSTALLER Button on circuitpython.org ## Advanced: Install TinyUF2 Bootloader Only You can also use OPEN INSTALLER to install only the TinyUF2 bootloader, and skip installing CircuitPython. Choose **Install Bootloader Only** from the installer menu dialog box. ![install CircuitPython BIN file](https://cdn-learn.adafruit.com/assets/assets/000/138/784/medium800/circuitpython_web-firmware-installer-menu-uf2-bin-only.png?1754422275 ) You will see the dialog boxes for making a serial connection and erasing flash, as described on the [Boards With Full USB Support page](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support). First you'll see [Connect to Your Board](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support) (click for details) and you'll select the serial port. ![connect to serial port](https://cdn-learn.adafruit.com/assets/assets/000/138/787/medium800/circuitpython_web-firmware-installer-serial-connect.png?1754423080 ) Next you'll see the [Erase Flash](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support) box (click for more details). In general, don't skip erasing the board. ![Erase Flash](https://cdn-learn.adafruit.com/assets/assets/000/138/786/medium800/circuitpython_web-firmware-installer-erase.png?1754422955 ) Finally you'll see this **Flashing ...** box, showing that the installer is flashing TinyUF2 to the board. When it finishes, you'll be done. ![TinyUF2 installation](https://cdn-learn.adafruit.com/assets/assets/000/138/788/medium800/circuitpython_web-firmware-installer-tinyuf2-install.png?1754423679 ) # Using the OPEN INSTALLER Button on circuitpython.org ## Serial-Only Boards Danger: This page is for boards that only present as a USB serial device or don't have any USB capability. This includes Espressif ESP32, ESP32-C2, ESP32-C3, ESP32-C6, and ESP32-H2. For boards that have full USB support and can present as a disk drive, like ESP32-S2, ESP32-S3, and ESP32-P4, see [Boards with Full USB Support](https://learn.adafruit.com/using-open-installer-on-circuitpython-org/boards-with-full-usb-support). ![OPEN INSTALLER button on circuitpython.org](https://cdn-learn.adafruit.com/assets/assets/000/138/775/medium800/circuitpython_open-installer-bin-only.png?1754414351 ) Most boards with Espressif microcontrollers [on circuitpython.org](https://circuitpython.org/downloads) provide a button labelled **OPEN INSTALLER**. Clicking this button invokes the [Web Firmware Installer](https://github.com/adafruit/web-firmware-installer-js) tool. On boards with full USB support, using this guided tool, you can: - Erase the flash on a board - Install CircuitPython - Fill in **settings.toml** with your desired network settings. You can skip some or all of these steps, as needed. Currently, the **OPEN INSTALLER** button is only present on the download pages for Espressif boards, but it may be added to other types of boards in the future. ## Opening Dialog To use the Web Firmware installer, first go to [https://circuitpython.org/downloads](https://circuitpython.org/downloads), find the entry for your board, and click on it. You will go to the download page for your particular board. There will probably be two **OPEN INSTALLER** buttons on the page, one for the current stable version of CircuitPython, and one for the latest development release. Choose the one you want to use. When you click **OPEN INSTALLER** , you will first see the dialog box below. The name of your board will be mentioned in the first paragraph. Read the text if you haven't before, and then click  **Next**. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/714/medium800/circuitpython_web-firmware-installer-1.png?1754338825 ) ## Installer Menu The next dialog box you see gives you a menu of choices. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/716/medium800/circuitpython_web--firmware-installer-menu-bin.png?1754338929 ) - A **Full CircuitPython Install** will install install CircuitPython using a BIN file. Then you will then be asked to supply WiFi credentials, which will be written to **settings.toml**. - **Install CircuitPython BIN only** installs CircuitPython, and skips the WiFi credentials step. - Update WiFi credentials assumes CircuitPython is already installed. It will write the WiFi credentials you enter to **settings.toml**. This Guide page describes the **Full CircuitPython Install** , as shown below. The other choices do less:  **Install CircuitPython Bin Only** choice stops before updating WiFi credentials, and **Update WiFi credentials** starts there, skipping the CircuitPython install. ![Full CircuitPython Install](https://cdn-learn.adafruit.com/assets/assets/000/138/790/medium800/circuitpython_web-firmware-installer-menu-bin-full-install.png?1754428263 ) ## Connect to Your Board The next dialog box you see will be the one below. Follow the instructions to connect your board to your computer with a data-capable USB cable, and then put the board into ROM bootloader mode. It is easier to identify the right serial port if you disconnect any other boards or other serial devices. ![](https://cdn-learn.adafruit.com/assets/assets/000/138/717/medium800/circuitpython_web-firmware-installer-serial-connect.png?1754338990 ) When you click the **Connect** button, a dialog box will appear for you to select the serial port. The images below show how this dialog box appears on Windows, macOS, and Linux. Choose the serial port (step 1 in the screenshots), and then click  **Connect** or **Select Folder** (step 2). - On Windows, the serial port will be `COMnn`. - On Linux, the serial port will usually be something like `/dev/ttyACMn`, `/dev/ttyAMAn`, or `/dev/ttyUSBn`.  - On macOS, the serial port will be `cu.something`. ![connect to serial port](https://cdn-learn.adafruit.com/assets/assets/000/138/751/medium800/circuitpython_web-firmware-installer-serial-connect-all.png?1754404694 ) ## Erase Flash The next dialog box after **Connect to Your Board** will ask if you want to erase the flash on your board. In general, don't click **Skip Erase** , but you can if you are sure you want to preserve the parts of flash that won't get overwritten. Danger: Installing firmware can erase the data you have stored on the board in CIRCUITPY. Using **Erase Flash** definitely will! Back up your data before proceeding. ![Erase Flash](https://cdn-learn.adafruit.com/assets/assets/000/138/718/medium800/circuitpython_web-firmware-installer-erase.png?1754339154 ) If you choose to erase the flash, you'll see this spinning for a bit: ![spinning "erasing" indicator](https://cdn-learn.adafruit.com/assets/assets/000/138/719/medium800/circuitpython_web-firmware-installer-erasing.png?1754339182 ) ## CircuitPython BIN Installation Now the installer will download CircuitPython and flash it to the board. ![flash CircuitPython BIN file](https://cdn-learn.adafruit.com/assets/assets/000/138/780/medium800/web-firmware-installer-circuitpython-bin.png?1754416249 ) ## Fill in **settings.toml** The last step is to specify network settings. First, the installer will ask you to reconnect to the serial port, so it can send commands to write to CIRCUITPY. Click the **Connect** button and choose the serial port, as you did above. ![Reconnect to serial](https://cdn-learn.adafruit.com/assets/assets/000/138/779/medium800/circuitpython_web-firmware-installer-reconnect-to-serial.png?1754416087 ) Finally, the installer will ask for network settings, and then will write those settings to the  **settings.toml** file on CIRCUITPY. If you don't want to fill in these values now, just close the box, or leave the values blank and click **Next**. ![Fill in settings.toml](https://cdn-learn.adafruit.com/assets/assets/000/138/725/medium800/circuitpython_web-firmware-installer-settings-toml.png?1754341393 ) ## Done! Now you're all done! ![](https://cdn-learn.adafruit.com/assets/assets/000/138/724/medium800/circuitpython_web-firmware-installer-done.png?1754341368 ) ## Related Guides - [Adafruit RP2040 CAN Bus Feather](https://learn.adafruit.com/adafruit-rp2040-can-bus-feather.md) - [IoT Food Scale with Azure and CircuitPython](https://learn.adafruit.com/iot-food-scale-with-azure-and-circuitpython.md) - [Bluefruit TFT Gizmo ANCS Notifier for iOS](https://learn.adafruit.com/ancs-gizmo.md) - [CircuitPython Connected Weather Cloud Lamp](https://learn.adafruit.com/circuitpython-connected-weather-cloud.md) - [PyPortal IoT Plant Monitor with Microsoft Azure IoT and CircuitPython](https://learn.adafruit.com/using-microsoft-azure-iot-with-circuitpython.md) - [Cyber Cat MIDI Keyboard](https://learn.adafruit.com/midi-cyber-cat-keyboard.md) - [Adafruit CCS811 Air Quality Sensor](https://learn.adafruit.com/adafruit-ccs811-air-quality-sensor.md) - [Analog Devices ADT7410 Breakout](https://learn.adafruit.com/adt7410-breakout.md) - [Adafruit MagTag Project Selector](https://learn.adafruit.com/adafruit-magtag-project-selector.md) - [Christmas Soundboard with NeoTrellis M4](https://learn.adafruit.com/xmas-sound-board.md) - [Flapping Halloween Vampire Bat](https://learn.adafruit.com/flapping-halloween-vampire-bat.md) - [Adafruit Proto Tripler PiCowbell](https://learn.adafruit.com/adafruit-proto-tripler-picowbell.md) - [Generating Text with ChatGPT, Pico W & CircuitPython](https://learn.adafruit.com/generating-text-with-chatgpt-pico-w-circuitpython.md) - [Driving TM1814 addressable LEDs](https://learn.adafruit.com/driving-tm1814-addressable-leds.md) - [PyPortal IoT Data Logger with Analog Devices ADT7410, Adafruit IO and CircuitPython](https://learn.adafruit.com/iot-pyportal-data-logger-adafruitio-circuitpython.md)