You Need Python 3 and pip3

To run CircuitPython BLE libraries on a host computer, you'll need at least Python 3.9, and you'll need the pip3 program to install the libraries. You may have pip already, but often the pip (not pip3) command installs software for Python 2, so make sure you are using pip3.

Windows 10

You can install Python from https://python.org, or from the Windows Store. See our guide Using Python on WIndows 10 for an easy way to get Python installed.

If you don't use the Windows Store version, make sure you check the box to add Python to your PATH when you run the installer. See the screenshot below.

Starting Python 3 on Windows

Depending on how you install Python 3, the command to start it in a command shell in Windows can be different.

• Installed from the https://python.org download:
  • Works: python (python.exe)
  • Works:py (py.exe, the Python launcher).
  • Does not work: python3 (python3.exe). You'll get directed to the Windows Store to install Python 3 yet again.
• Installed from the Windows Store:
  • Works: python (python.exe)
  • Does not work: py (the Python launcher is not installed).
  • Works: python3 (python3.exe).

These differences can be confusing; see this page for detailed documentation.

macOS

Modern macOS comes with Python 3, but it may be an older version. Instead of using the system-supplied version, we recommend that you use the Homebrew system to install a more recent version of Python 3 and keep it up to date. The Homebrew installation will not interfere with the system-installed Python, and does not replace it.

This article describes in detail various ways of managing Python on macOS. It's worth reading to understand the issues, and to see various ways of managing multiple versions of Python.

Bluetooth Permissions

A user has reported that, at least as of macOS Big Sur, you must add your terminal application to the Bluetooth Privacy Settings in System Preferences > Security & Privacy > Privacy > Bluetooth.

Linux

Modern versions of Linux always come with Python. They may include both Python 2 and Python 3. See if the version supplied with your Linux distribution is at least 3.9. If not, your distribution may allow you to install additional versions that do not interfere with the original system-supplied version. If you can upgrade your distribution, considering doing so. For instance, Ubuntu 22.04 comes with Python 3.10.

Make sure you have pip3 installed as well, by trying to run it. If it's not installed, install it in the appropriate way for your Linux distribution. For instance, for Ubuntu and Debian, do:

Raspberry Pi OS

Raspberry Pi OS (the new name for Raspian), which is based on Debian Linux, also comes with Python. The latest version as of this writing (April 2023), bullseye, comes with Python 3.9, invoked with the python3 command.

If you are using Raspberry Pi OS Lite, it may not come with pip3. You'll need to install it by doing: 

Do Not Use sudo When Running pip3

You may see Internet advice to install libraries using sudo pip3 on Linux or MacOS. This is in general a bad idea, because you can damage the libraries that the underlying system depends on, and in general end up trashing your system in mysterious ways. Always install using pip3 without sudo. If your pip3 is old, you may need to specify pip3 --user, but these days --user is often the default.

Here's a detailed discussion of why sudo pip3 is a bad idea.