Installing on Mac and Linux

The installation process for Jupyter and the CircuitPython kernel is a bit lengthy, but it's not difficult. If you don't already have Jupyter installed, you'll need to install it before we install the kernel. 

If you have a WIndows machine, please skip to the next page with Windows specific installation instructions.

Installing Jupyter

Install Jupyter with Anaconda

Don't have a Python installation on your computer? If you're new to all this, the Jupyter Project recommends installing Anaconda, which installs Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science.

First, navigate to the Anaconda downloads page, select your platform (Windows, Mac, Linux), and download the installer including Python 3.6+.

Install the version of Anaconda you downloaded by following the instructions in the installation executable. 

Install Jupyter with PIP

The CircuitPython Jupyter Kernel requires a Python 3.6+ installation.

If you have a Python installation already on your computer, you may want to use the Python Package Manager (pip) instead of Anaconda. 

If you're not sure which Python version is installed, you can check by running:

Download: file
python3 --version

Next, let's ensure we also have the latest version of the Python Package Manager. We can do this by running:

Download: file
pip3 install --upgrade pip

Install the Jupyter Notebook:

Download: file
pip3 install jupyter

Starting the Notebook Server

Now that we have Jupyter installed, let's start the notebook server.

On MacOS or Linux, we can use the Terminal.

Let's launch the Jupyter Notebook server by opening either Command Prompt or Terminal and typing:

Download: file
jupyter notebook

If your installation went well, you'll see information about the notebook server in your command line:

Your web browser will automatically open to the Jupyter Notebook Dashboard.

The Notebook Dashboard displays a list of notebooks, files, and folders in the location on your computer from where the notebook server was started.

We're going to spend more time with the Dashboard later in this guide.

Installing the CircuitPython Kernel

Jupyter manages its programming language support through the installation of kernels.

By default, the Jupyter Notebook will have the Python programming language installed. We're going to install the CircuitPython Kernel which is a wrapper which allows CircuitPython's REPL to communicate with Jupyter's code cells.

If you have a Git client installed, clone the CircuitPython kernel by running the following in your terminal:

Download: file
git clone https://github.com/adafruit/circuitpython_kernel.git

Alternatively, you can download the latest release of the circuitpython_kernel from GitHub as a .zip file and unzip it.

In your terminal or command prompt, navigate to the folder directory:

Download: file
cd circuitpython_kernel/

Install the Kernel by running:

Download: file
python3 setup.py install

Finally, let's install the CircuitPython Kernel into Jupyter:

Download: file
python3 -m circuitpython_kernel.install
You may need to run this command prefixed by 'sudo' on MacOS or Linux if you see errors during the installation.

The kernel should be installed, but let's verify that by running:

If circuitpython appears as an available kernel, the installation was successful. 

This guide was first published on Jul 03, 2018. It was last updated on Jul 03, 2018. This page (Installing on Mac and Linux) was last updated on Aug 24, 2019.