skip to Main Content


Adafruit regularly updates information on how to install CircuitPython, which you can find at Adafruit’s page and follow their copy/paste instructions. If you ever run into problems or need information beyond the instructions below, visit that page, Adafruit’s Discord Channel, or the Adafruit forums.

Tools Needed:

This video assumes you’ve got a Raspberry Pi that will work over Wi-Fi, a power source for the Pi, and that you’ve configured a microSD card for the Pi, installing latest version of Raspbian Lite to work over Wi-Fi. If you haven’t performed these steps, see:

This tutorial was written to install CircuitPython on a Pi as part of follow-along videos for building an iOS-controlled Raspberry Pi robot, but the steps below can be used to set up any Raspberry Pi on a network requiring a single password. The tutorial assumes you’re using a Mac (which will be needed if you’re going to use write an iOS app to control the robot).


Prefer video instruction? Use the follow-along YouTube video that covers the steps, below.

Step 1: Launch Terminal and Log Into Your Pi

  • Launch the Terminal program on your Mac by pressing Command-Space to launch Spotlight, then type Terminal, and press the return key.
  • Log into your Pi using the command below replacing hostname with your Pi’s hostname, then press the return key. REMINDER for my students on campus – don’t use “.local” in your ssh line when logging in to your Pi while it is connected to the BostonCollege network.
    ssh pi@hostname.local
  • Enter your Pi’s password when prompted, and press the return key.

Step 2: Install / Upgrade pip on your Pi

We’ll install pip, which is a tool to install additional python software packages from the popular Internet site: Python Package Index (PyPI). Starting with Raspberry Pi OS Bullseye, pip3 and python3 were default, so as long as you’re using the native OS there’s no reason to enter pip3, just pip. Same with using python instead of the old python3. To setup pip on your Pi perform these steps:

  • From the command prompt in terminal, enter the command below and press the return key.
    sudo apt-get install python3-pip
  • Whenever you’re prompted to confirm if it’s OK to use additional disk space, type “Y” and press the return key, and installation will resume.
    If you get a message: Package ‘python-pip’ has no installation candidate, don’t worry. If you’re using the latest Raspberry Pi, then this is likely already installed
  • Now enter the command below and press the return key. Note: This installation might look like it’s frozen during the first minute or two of operations. Be patient and things should start to move on the terminal screen.
    sudo pip3 install --upgrade setuptools

Step 3: Run the Adafruit Pi Installer Script

Adafruit has created a script to make sure the Pi is properly configured with Blink installed.

  • Copy the block of code below, paste it into the command prompt on your Pi, then press return:
    cd ~
    sudo pip install --upgrade adafruit-python-shell
    sudo python

NOTE: If the script above doesn’t work

There is a chance the script above might not work. For example, shortly after Raspberry Pi OS “Bullseye” was released, the procedure above broke because additional files needed updating. If you get a message stating something similar to the text below:

Blinka Some packages could not be installed. This may mean that you have 
Blinka requested an impossible situation or if you are using the unstable
Blinka distribution that some required packages have not yet been created
Blinka or been moved out of Incoming.
Blinka The following information may help to resolve the situation:
Blinka The following packages have unmet dependencies:
Blinka vlc-bin : Depends: libvlc-bin (= 3.0.16-1+rpi1+rpt1) but 3.0.16-1+rpi1+rpt2 is to be installed
Blinka vlc-plugin-skins2 : Depends: vlc-plugin-qt (= 3.0.16-1+rpi1+rpt2) but 3.0.16-1+rpi1+rpt1 is to be installed Blinka Exiting due to error: Apt failed to install software!

If you see a message similar to the one above, you can attempt a full install with this command:

  • sudo apt full-upgrade

After entering the command above, it’s a good idea to run the command below, which will remove any now-redundant package files.

  • sudo apt clean
  • When you return to the prompt, copy the block of code below (the same one that failed earlier), paste it into the command prompt on your Pi, then press return:
    cd ~
    sudo pip install --upgrade adafruit-python-shell
    sudo python

With luck you will see that the installation now works properly.

Step 4: Reboot When Asked

When the installation above is done and you’ve been returned to the command prompt, you’ll be asked if you want to reboot your Pi.

  • Select Yes. Your Pi should reboot. Once this happens wait about 30 seconds, then log in with ssh commands, as usual (my students on campus, remember to eliminate “.local” when logging in over the BostonCollege network):
    ssh pi@hostname.local

Step 5: Check on the I2C and SPI Configuration

If you’ve followed the earlier CircuitPython School videos that covered CircuitPython on Microcontrollers (e.g. CircuitPlayground Bluefruit, Arduino Nano RP2040 Connect, Adafruit QT Py), you may recall our discussion of I2C and SPI.

I2C (often pronounced “eye-squared-see”) stands for Inter-Integrated Circuit, and it’s a popular standard that allows a Raspberry Pi (as well as other devices) to communicate with things that are attached to it, like motors and sensors. SPI is also used in the STEMMA-QT and Qwiic, one-plug connection cabling system.

SPI (sometimes pronounced “spy”) stands for Serial Peripheral Interface, and like I2C, it’s also a standard to allow a device to communicate with peripherals. SPI requires more wiring and is often the choice devices that sends. higher data-volume. 

  • Verify the installation of SPI by entering the statement below at the prompt, then pressing the return key:
    ls /dev/i2c* /dev/spi*

If this installation is successful, you will see output that looks something like this:
/dev/i2c-1 /dev/spidev0.0 /dev/spidev0.1

If it is not successful, you will get a message like this:
ls: cannot access ‘/dev/spi*’: No such file or directory

If you are not successful, consult Adafruit’s learn guide for Installing CircuitPython on a Raspberry Pi and repeat the steps included there. 

Step 5: Run the Blinka Test Program

Adafruit Blinka is a software tool that allows us to run Adafruit’s popular and easy-to-use CircuitPython libraries (originally used just on the firm’s Arduino-compatible products, but now implemented on hundreds of boards) on a Raspberry Pi. It’s a really well supported set of Python libraries (for questions, see Adafruit’s Discord Channel (inhabited by an incredible group of highly-skilled makers eager to provide all levels of advice), as well as the excellent support on these forums is just one of the many reasons to buy products from Adafruit). Blinka is also the name of CircuitPython’s purple snake mascot. 

Blinka should have been installed in the scripts you entered earlier. To test the Blinka installation on your raspberry Pi:

  • Create a blank file called using the nano text editor by typing the following command at the Terminal command prompt, then press the return key:

    This creates a blank file named

  • Now copy the code below (it can also be found at:
    import board
    import digitalio
    import busio
    print("Hello blinka!")
    # Try to create a Digital input
    pin = digitalio.DigitalInOut(board.D4)
    print("Digital IO ok!")
    # Try to create an I2C device
    i2c = busio.I2C(board.SCL, board.SDA)
    print("I2C ok!")
    # Try to create an SPI device
    spi = busio.SPI(board.SCLK, board.MOSI, board.MISO)
    print("SPI ok!")
  • Type Control-X to quit nano.
  • Type “Y” when asked if you’d like to save the file.
  • Press the return key after the file name and you’ll be returned to the command prompt.
  • Now execute the program by entering the command below, followed by the return key:

    If everything works, you’ll see the print statements have printed without any errors:

    Hello blinka!
    Digital IO ok!
    I2C ok!
    SPI ok!

If everything works, congratulations! You’re ready to continue with your CircuitPython Raspberry Pi project. There are more Raspberry Pi-based CircuitPython tutorials at:

If you’ve completed the steps above as part of the Let’s Build a Robot project, we’re ready to attach our motors to the Pi, and test them. There are versions of the next step instructions for projects using the Adafruit DC & Stepper Motor HAT for Raspberry Pi – Mini Kit as well as the WaveShare Motor Driver HAT for Raspberry Pi, I2C Interface. Find the next document in this series and links to accompanying step-by-step YouTube videos at:

If you’re following this tutorial as part of the iOS-controlled “Make It Talk” project (Talking Yoda), return to the MakeItTalk project start page.

❖    ❖    ❖    ❖    ❖

Ready for more? Check out tutorials on Robotics, Wearables, App Development and more at: There is a full playlist for CircuitPython on microcontrollers that I use for my Physical Computing course. You’ll find this at: while the Raspberry Pi tutorials are at: Please consider subscribing and do share with others who may be interested!

Want to learn to build apps? The same content I use in my semester-long online course (videos and tutorial content) is available for less than $25 via links you’ll find at

Look for more updates at as well as on Twitter @gallaugher


Back To Top