What is all this fuss about IPython Notebook? Here is a simple sample I made in a couple minutes and it uses the attention getting XKCD plot from matplotlib. When you are looking at this, you can check out much more sophisticated examples here.

Installing on OS X Lion. This went very smoothly using Python’s virtualenv. Using the Python that comes with OS X: Rarely has something open source and so useful installed so painlessly!

$sudo pip install virtualenv

Create a folder in your home directory for virtual Python environments. I created another folder inside for a project called TestProject. I plan on using IPython Notebook for projects so the main folder is IPNB and TestProject is inside. To make sure everything is going in the right place, I navigate to the new project folder. I will have a full install of everything needed, won’t interfere with other projects, and it can be thrown out if it gets wrecked. I’m using Python3.4 and calling the test venv  ‘simtest’.

Note: Do not use sudo from here on! Repeat this part for every project, changing names of course.

$cd Documents/IPNB/TestProject

$python3 -m venv simtest
$ls
$simtest

If you get an error about badly placed ()’s, you are not in bash. Just type bash at the prompt to temporarily switch to the bash shell.

Navigate to the venv folder and activate the venv. When activated, the prompt will change to show the venv you are in.

$cd simtest
$source bin/activate
(simtest)$

(simtest)$pip install "ipython[notebook]"

# Lots of stuff ......

I also installed matplotlib.

$ pip install matplotlib
# More stuff ......

Deactivate the venv and activate again.

(simtest) bash-3.2$ deactivate
$ source bin/activate

Start your notebook

ipython3 notebook

Note you need to use ipython3 to run python3 versions. Repeat this for every new project and you can load and remove any special modules and libraries without affecting other projects or dependencies.

Debian Wheezy. I had lots of errors following various tutorials. This works for me and follows this page. I have only added a gotcha about the shell you are using and the location of the Python sources. (I’m using 32 bit Debian for other compatibility reasons.)

Start by making sure some dependencies are installed. You can do this from your home directory.

~$ sudo apt-get install build-essential
~$ sudo apt-get install libncurses5-dev libncursesw5-dev libreadline6-dev
~$ sudo apt-get install libdb5.1-dev libgdbm-dev libsqlite3-dev libssl-dev
~$ sudo apt-get install libbz2-dev libexpat1-dev liblzma-dev zlib1g-dev

Now set up pip with a config file. Don’t ask me what it means, still learning!

~$ mkdir -p ~/.pip/cache
~$ echo '[global]' > ~/.pip/pip.conf
~$ echo 'download_cache = ~/.pip/cache' >> ~/.pip/pip.conf

Get the Python sources you need here on the Python downloads page. The tarball should go to the /tmp directory. I chose the Python 3.4.3 gzipped tarball.

~$ cd /tmp
$ tar -zxf /path/to/your/Python-3.4.3.tgz
$ cd Python-3.4.3
$ ./configure --prefix=/usr/local/opt/python-3.4.3
$ make
$ sudo make install
$ cd /tmp
$ sudo rm -rf Python-3.4.3

Lots of stuff happens with the make commands. If you have multiple cores, you can speed it up with make’s -j option for multiple threads. I have an AMD quad core and used make -j8. Note that as the text flies by there are lots and lots of lines that look like errors. They are OK. Everything built without problems.

The virtual environment. The part you repeat for each project. I’m using Python3 with built in pyenv, an organizing tool for multiple versions of Python that can also provide a simple virtual environment. If you need virtualenv, find directions to install similar to the OSX  above. Here is setting up a pyenv for Python 3.4.3 in the home directory and a projects sub-directory I call IPNB (for IPython Notebook) and a sub-directory for testing, /project1.

$ cd ~/IPNB/project1
~/IPNB/project1$ /usr/local/opt/python-3.4.3/bin/pyvenv virtualenv-3.4.3

I gave the pyenv a long descriptive name, “virtualenv-3.4.3” for this example. It is worthwhile thinking up shorter names because the name is prefixed on every line in the terminal once the virtual environment is activated. You can see it uses the environment constructor from Python 3.4.3 in the /user directory to make the pyenv in the home based ~/IPNB/project1 directory. It also makes fresh copies of Python and everything needed in the new pyenv. Here is a little info on pyenv.

Now activate the pyenv.

$cd project1
$source virtualenv-3.4.3/bin/activate
(virtualenv-3.4.3)$

If you get a command not found error, you are not running the bash shell. Type bash and enter, and try again. Install IPython notebook.

(virtualenv-3.4.3)$pip install "ipython[notebook]"

Your Python version may not include pip. Install it and try again.

Lots of stuff happens……. Install matplotlib.

(virtualenv-3.4.3)$ pip install matplotlib

Lots more stuff happens….. Now deactivate and re-activate the pyenv so it is updated.

(virtualenv-3.4.3)$ deactivate 
$ source virtualenv-3..4.3/bin/activate

You can now launch the notebook and open an existing sample or create a new one. Note that ipython3 notebook is needed if you are using Python 3. For 2.6 or 2.7, just use ipython notebook.

ipython3 notebook

A page will open in your browser – if it doesn’t, you can use the URL that is printed out in the terminal window when notebook starts. You can navigate to other places to get or save notebooks. Note that you can not use the terminal window after this. It will display saves and any other activities. You quit by control-c in the terminal window that you used to launch. control-c twice to skip the [Y/n]. If you need to do other terminal work, you will have to open more terminals.

I have but the notebook files outside the pyenv directory and inside the enclosing project directory. In this case, outside /simTest and inside /venvTest. I should have picked better names. In other owrds, /simTest and pyenv are at the same level. I have no idea if this is optimal or the intention of the creators of IPNB and pyenv.