PyCharm is a full-featured Python editor that includes super helpful things like code completion and error highlighting. It's available for free in a Community Edition.

These steps will help you make the most out of the PyCharm IDE for working with CircuitPython:

Disable Auto-save

By default, PyCharm will auto-save the code file(s) that you are working on very frequently. This is normally great, but with CIRCUITPY drives, it is can be undesirable because it will cause the device to reset and re-run the code more frequently than you might want. When you're using PyCharm to edit files directly on CIRCUITPY drives, it's best to disable the auto-save features and save manually with CTRL+S whenever you're ready to run the new version of

To disable auto-save, follow these steps:

  1. Open settings with CTRL+ALT+S or click File -> Settings
  2. Open up Appearance & Behavior -> System Settings
  3. Uncheck the box for "Save files if the IDE is idle for X seconds"
  4. Uncheck the box for "Save files when switching to a different application"

Creating a project on a computer's file system

PyCharm likes to create a folder named .idea which holds configuration settings and meta information about your project. This folder gets created in the root directory of the project that you are working in. Ideally, we don't want this to end up on the CIRCUITPY drive, because it will eat up precious storage space and cause the device to reset when files inside of it are altered. The way we avoid this is by creating our project on the computer's hard drive and then adding CIRCUITPY or the directory that contains it as a "content root" so that PyCharm will show the files on the CIRCUITPY drive as part of the project.

  1. Click File -> New Project
  2. Enter a name for the project. I like to use DEVICE_WORKSPACE but you can choose any name you like
  3. Enter or browse to a location on your computer's hard drive to store the project directory in
  4. Click the Create button
  5. With your new project open, click File -> Settings or press CTRL+ALT+S to open the settings window
  6. Open "Project [YOUR_PROJECT_NAME]" then click "Project Structure"
  7. Click the "+ Add Content Root" button on the right side of the window

The next step depends on your host OS.

If you are on Linux, type or navigate to /media/[username]/ where [username] is your actual username on the computer. Click "Okay" to add this directory as the content root.

If you are on Mac, type or navigate to /Volumes/ then click "Okay" to add this directory as the content root.

If you are on Windows, type or navigate to the drive letter that matches your CIRCUITPY drive, e.g. D:\, then click "Okay" to add this directory as the content root.

On Windows, the content root that you've added may eventually show up empty if you open the project when the CircuitPython device is not connected, or if the drive letter on your device changes due to other removable storage devices getting plugged in. Repeat the above instructions to re-add the device with its current drive letter. You can also click the "X" on the old / non-working content roots to remove them from the list in the same settings window.

After completing these steps, you'll have a project on your computer's hard drive which will get the .idea directory stored inside of it. And you'll also have access to the CIRCUITPY drive(s) that are connected to your computer.

Install circuitpython-stubs

The circuitpython-stubs will let PyCharm know more information about the built-in core modules in CircuitPython so that it can offer relevant code hints and typing information. The stubs are published on PyPi, and installing them can be done in the PyCharm settings window.

  1. Click File -> Settings or press CTRL+ALT+S to open the Settings window
  2. Open "Project: [YOUR_PROJECT_NAME]" then click Python Interpreter
  3. Click the + install button on the right side of the window
  4. Type "circuitpython-stubs" into the search bar
  5. Select the circuitpython-stubs package then press the Install Package button at the bottom left 

Device Specific Board Stubs

Starting with CircuitPython 9.0 the circuitpython-stubs now allow you to set a device and get specific board definition stubs for that board.

After installing the stubs run this command:

circuitpython_setboard [board_id]

i.e. circuitpython_setboard adafruit_feather_esp32s3_tft

To find a list of valid board IDs you can look in the circuitpython core repo inside of:


i.e. for espressif boards find the list of directories in: ports/espressif/boards/

Install Libraries

If you project uses libraries from the CircuitPython Library Bundle, you can install them on your computer if they are published to PyPi. Doing so will give PyCharm information about the library in order to offer more relevant code hints and type information.

Use the above instructions to open the Available Packages window, then enter "adafruit-circuitpython-" into the search box to see all of the libraries deployed to PyPi.

Serial console in the terminal pane

If you use the instructions from Advanced Serial Console on Mac or Advanced Serial Console on Linux, you can connect to the CircuitPython device's serial console inside the Terminal pane within PyCharm.

To open the Terminal pane, click View -> Tool Windows -> Terminal.

Connect to your device using screen or tio. Then, you can see output and interact with the device and REPL.

This guide was first published on Dec 19, 2017. It was last updated on May 26, 2024.

This page (PyCharm and CircuitPython) was last updated on Mar 28, 2024.

Text editor powered by tinymce.