Setup Virtual Environment

If you are installing on the Bookworm (released in 2023) or later version of Raspberry Pi OS, you will need to install your python modules in a virtual environment. You can find more information in the Python Virtual Environment Usage on Raspberry Pi guide. To Install and activate the virtual environment, use the following commands:

cd ~
sudo apt install python3-venv
python3 -m venv env --system-site-packages

source env/bin/activate

Python Installation of NeoPixel Library

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

For more recent versions of Python, you will need to set up a Virtual Environment as described in the above linked guide.

Once that's done, from your command line run the following command:

pip3 install rpi_ws281x adafruit-circuitpython-neopixel
python3 -m pip install --force-reinstall adafruit-blinka

If you have a Raspberry Pi 5 and need NeoPixels working, you have a couple of options.

If you don't want to bother with software updates and don't need it for other peripheral, you can use the SPI port. Check out the CircuitPython NeoPixel Library Using SPI guide for more information.

If you need the SPI port for other hardware and don't mind potentially doing software updates, check out the Using NeoPixels on the Pi 5 guide for more information.

Python Usage

To demonstrate the usage of this library with NeoPixel LEDs, we'll use the Python REPL.

sudo -E env PATH=$PATH python3

sudo -E env PATH=$PATH python3 neopixel_rpi_simpletest.py

import board
import neopixel
pixels = neopixel.NeoPixel(board.D18, 30)

Depending on the specific NeoPixels you have connected, you may need to add some additional parameters to the initializer. Here are a couple common ones:

• bpp - Bytes Per Pixel. Defaults to 3. Set this to 4 if you have RGBW NeoPixels. If you try to fill the NeoPixels with a solid color and they light up as different colors, you will probably want to change this.
• pixel_order - If you are seeing the NeoPixels light up as the same colors, but they are a different color than you expect, you may need to change this value.

Now you're ready to light up your NeoPixel LEDs using the following properties:

• brightness - The overall brightness of the LED
• fill - Color all pixels a given color.
• show - Update the LED colors if auto_write is set to False.

For example, to light up the first NeoPixel red:

pixels[0] = (255, 0, 0)

pixels.fill((0, 255, 0))

That's all there is to getting started with NeoPixel LEDs on Raspberry Pi!

Below is an example program that repeatedly turns all the LEDs red, then green, then blue, and then goes through a single rainbow cycle. If you chose a pin other than D18 for your NeoPixels, change the pin to match the pin you chose to use to connect the NeoPixels to your Raspberry Pi. If you're using a different number of NeoPixels, change num_pixels to match.

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
# Simple test for NeoPixels on Raspberry Pi
import time
import board
import neopixel
# Choose an open pin connected to the Data In of the NeoPixel strip, i.e. board.D18
# NeoPixels must be connected to D10, D12, D18 or D21 to work.
pixel_pin = board.D18
# The number of NeoPixels
num_pixels = 30
# The order of the pixel colors - RGB or GRB. Some NeoPixels have red and green reversed!
# For RGBW NeoPixels, simply change the ORDER to RGBW or GRBW.
ORDER = neopixel.GRB
pixels = neopixel.NeoPixel(
    pixel_pin, num_pixels, brightness=0.2, auto_write=False, pixel_order=ORDER
)
def wheel(pos):
    # Input a value 0 to 255 to get a color value.
    # The colours are a transition r - g - b - back to r.
    if pos < 0 or pos > 255:
        r = g = b = 0
    elif pos < 85:
        r = int(pos * 3)
        g = int(255 - pos * 3)
        b = 0
    elif pos < 170:
        pos -= 85
        r = int(255 - pos * 3)
        g = 0
        b = int(pos * 3)
    else:
        pos -= 170
        r = 0
        g = int(pos * 3)
        b = int(255 - pos * 3)
    return (r, g, b) if ORDER in {neopixel.RGB, neopixel.GRB} else (r, g, b, 0)
def rainbow_cycle(wait):
    for j in range(255):
        for i in range(num_pixels):
            pixel_index = (i * 256 // num_pixels) + j
            pixels[i] = wheel(pixel_index & 255)
        pixels.show()
        time.sleep(wait)
while True:
    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((255, 0, 0))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((255, 0, 0, 0))
    pixels.show()
    time.sleep(1)
    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((0, 255, 0))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((0, 255, 0, 0))
    pixels.show()
    time.sleep(1)
    # Comment this line out if you have RGBW/GRBW NeoPixels
    pixels.fill((0, 0, 255))
    # Uncomment this line if you have RGBW/GRBW NeoPixels
    # pixels.fill((0, 0, 255, 0))
    pixels.show()
    time.sleep(1)
    rainbow_cycle(0.001)  # rainbow cycle with 1ms delay per step