Material for the SciPy 2017 Cython tutorial
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

SciPy 2017 Cython Tutorial

2017-06-26 NOTE: the Windows-specific instructions below are untested. If you are a Windows-using tutorial-ee, please provide feedback (pull-request, email the author, tutorial slack channel) and corrections, thank you!

End goal

We need just a few things set up for this tutorial:

  • The contents of this repository.
  • A CPython interpreter (Python 3).
  • The Cython package (version 0.25) and a few other dependencies (see requirements_conda.txt).
  • A working C / C++ compiler.

It's the last requirement that can be a challenge, depending on your platform / OS. The standard GCC / clang compiler that is available on Linux / Mac (respectively) will work fine. Windows can be more of a challenge.

In an effort to make things more uniform, we are using a docker container that bundles everything together except for the contents of this repository.

Setup Instructions

  • Clone this repository and cd into it:
$ git clone
$ cd scipy-2017-cython-tutorial
  • If you've cloned earlier, git pull on the master branch to ensure you have the latest updates:
$ git pull

The tutorial has a few one-time requirements which we describe below.

One-stop-shop via Jupyter docker containers

The jupyter project has convenient self-contained docker containers with everything we need for this tutorial. We recommend this method provided you can install and use a recent version of docker on your platform. This path will ensure you have a functional environment that matches the one used by the instructor.

  • Install Docker for your OS.
  • Mac / Linux: Open up a terminal and execute
$ ./

Leave this terminal as-is and do not exit the running docker session.

Verify that your container is running by opening a separate terminal and running

$ docker ps
CONTAINER ID        IMAGE                    COMMAND                  CREATED             STATUS              PORTS                    NAMES
deadbeef            jupyter/scipy-notebook   "tini -- start-not..."   7 minutes ago       Up 7 minutes>8888/tcp   cython-tutorial

You should see output like the above, with a different CONTAINER ID. Importantly, you should see cython-tutorial under the NAMES column. You will see more than one row if you have other docker containers running.

  • Windows: Open up a powershell and run
$ launch-container.bat 

This will download an run the Jupyter scipy notebook docker image, and launch a notebook server.

  • If successful, jupyter will publish a URI like
  • Visit this URI in your browser, you should see the home page of a Jupyter notebook server, with a list of all files in this repository.

  • Open the test-setup ipython notebook, and execute all cells. All should execute without error or exception.

  • In a separate terminal (Mac / Linux) or powershell (Windows) window, navigate to this directory and run the command (Mac / Linux) or the docker-test-xtension.bat command (Windows).

  • You should see output like:

$ ./
running build_ext
building '' extension
gcc -pthread -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -fPIC -I/opt/conda/include/python3.5m -c xtension/foo.c -o build/temp.linux-x86_64-3.5/xtension/foo.o
gcc -pthread -shared -L/opt/conda/lib -Wl,-rpath=/opt/conda/lib,--no-as-needed build/temp.linux-x86_64-3.5/xtension/foo.o -L/opt/conda/lib -lpython3.5m -o build/lib.linux-x86_64-3.5/xtension/
copying build/lib.linux-x86_64-3.5/xtension/ -> xtension
sys.executable: /opt/conda/bin/python
cython version: 0.25.2
xtension module test (31.415926): 31.415926
  • If you see an error like Error: No such container: cython-tutorial, then you likely shut down the docker container before running the test. Re-launch the container (./ and in a separate terminal run the script again.

Platform-specific (non-docker) setup instructions

These instructions are for those who can't or don't want to use the recommended docker-based installation above.

Mac-specific setup (non-docker)

  • Ensure you already have XCode / Mac OS developer tools / command line tools installed; if not, do so for your version of Mac OS. Check your install by running the following from the commandline:
$  gcc --version
Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 8.0.0 (clang-800.0.42.1)
Target: x86_64-apple-darwin15.6.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

Linux-specific setup (non-docker)

  • Ensure you have the packages necessary for gcc and related headers for your distribution. Check that you have a recent version of gcc installed:
$  gcc --version

Windows-specific setup (non-docker)

NOTE: untested -- please provide feedback!

General setup after compiler / dev tools are installed (non-docker)

  • If you haven't already, install Miniconda.

  • Create a cython-tutorial environment for this tutorial, using the requirements_conda.txt file provided:

$ conda create --yes -n cython-tutorial --file ./requirements_conda.txt
$ source activate cython-tutorial
  • Launch a jupyter notebook server
$ jupyter notebook
  • Open the test-setup notebook and run all cells. All should execute without error or exception.