Assignment 0 - Jupyter Notebook Setup

This assignment consists of setting up Jupyter (iPython) notebooks on your computer to prepare for Assignment 2, and for later parts of the course. While we feel confident everyone will be able to get the notebooks set up, there can be glitches so we want to ensure everyone is ready to go with plenty of time.

To Do: Once Jupyter is installed, load this test notebook that we have created, and verify that you are able to run every command in that notebook. Take a screenshot and upload proof that you managed to set up the Notebook (with no error messages).

Due Date: Sun Apr 9. There are NO LATE DAYS for this assignment -- we expect all students to have their installation verified by the deadline.

Installation Help: Installing Jupyter can be system-dependent, and you may run into unexpected errors that you aren't able to cope with on your own.
  • We will have office hours after class on Apr 6 Thursday 3-430pm in Lathrop Tech Lounge to help students troubleshoot their installations.
  • You can also scroll to the bottom for the troubleshooting section.
  • Post your question on Piazza, we will do our best to help you. It is difficult to debug online at times.

Installation Instructions

Here are some basic steps to install Jupyter on your laptop. Please ask any questions on errors that you're encountering. Choose from one of the following installation options:

  1. Installing Jupyter on Your Mac OS X Laptop Using A Script (FOR MAC USERS RECOMMENDED)
  2. Installing Jupyter on Your Mac OS X Laptop Manually (FOR MAC USERS)
  3. Installing Jupyter on Windows (FOR WINDOWS USERS)

1. Installing Jupyter on Your Mac OS X Laptop Using A Script (Recommended)

Here's a script that we wrote that you could try running on your Mac OS X laptop. We've verified that it works to some extent in Yosemite, El Capitan and Mac Sierra. It will outline what it's going to do before actually doing it, so it's safe to run. To run, just download it to some directory, open up Terminal, and run:

  • This might take a while, especially if your /usr/local directory has lots of files already.
  • If you see messages on installing command line tools, just install the command line tools and re-run the script again!


After you've done this, go to Steps 5 and 6 of the instructions below on how to run the notebook!

2. Installing Jupyter on Your Mac OS X Laptop Manually

Step 1: Install python, pip, and Homebrew:

These are really good things to have installed. Homebrew is very recommended especially if you have El Capitan; if you have Yosemite, you might be able to get by using the system Python, but if you have El Capitan, you'd be much better off using Homebrew Python.

  1. Python: This should come installed on most systems (try running "python" in your command line / terminal), however if not see here
  2. pip: If you have Python 2.7.9 or a later version of Python 2.7, you should have pip installed already. But if not, see instructions here
  3. Homebrew: See instructions here


Step 2: Ensure you have Command Line Tools installed:

xcode-select --install

After running the command above, a dialog box should open up, which you can follow to install the required components. If a message shows up saying something's already installed, just go on ahead.


Step 3: Install Homebrew Python:

Make sure you have installed Homebrew, and run:

brew install python


Step 4: Install Jupyter notebook:

Make sure you have installed Homebrew python, and run

pip install --upgrade jupyter ipython-sql matplotlib


Step 5: Running Jupyter notebooks:

Download the test notebook that we have made into some directory. In a Terminal, move into the directory where the downloaded notebook is, and run:

jupyter notebook


Step 6: Hello world:

To confirm that everything is working, download the test notebook, unzip it to the directory you ran the Jupyter notebook, and open by clicking on it in the newly opened browser tab. Click the top cell of the test notebook, and keep pressing Shift+Enter. Verify that you're seeing the correct output in the output cells for each input cell in the test notebook. Once you're done, come visit the TAs or Professor Widom after class or during OH and get yourself checked off for Assignment #2 Prerequisites.


The way it looks should somewhat represent the picture below, but not exactly.

Fig. 1: A notebook is for creative writing!


For (much) more detail about Jupyter notebooks, see the documentation.

3. Installing Jupyter on Windows

Step 1.

Install Python 2.7 Anaconda for Windows 64-bit at this link: . This is a huge file, so it might take a while. 

Step 2.

Run the .exe file and follow instructions to install it, when prompted, make sure the box for "Add Anaconda to my PATH environment variable" is checked and click "Install"

Step 3.

Open the "Command Prompt" application (for older version of Windows, this may be called the "cmd" application instead) and type:

 pip install ipython-sql

Step 4.

Note: This step is how you open up your jupyter notebook for future assignments!

In the "Command Prompt" application, type:

 jupyter notebook


Step 5.

In the web browser that was automatically opened, click "New"


Step 6.

Select "Python 2" in the drop down menu to test creating a new notebook. After finished, return to the previous page. 



Step 7. Hello world:

To confirm that everything is working, download test notebook .

Click "Upload".


Find the notebook you just downloaded in your file directory, and click "Open".


Click the blue "Upload" button to complete it. 


Now, you can see "Assignment0.ipynb" on your web browser, double click on it to open it. Click the top cell of the test notebook, and keep pressing Shift+Enter. Verify that you're seeing the correct output in the output cells for each input cell in the test notebook. 


Jupyter Setup Troubleshooting


If you're having trouble installing IPython notebook, look through the following fixes & try ones that seem potentially relevant.  If none of the below work then post your issue on Piazza!


If you are still having trouble, consider one of the alternative access methods- running on corn or running on Ubuntu VM (coming soon).


Remember, we don't "officially" support Windows, but the CA staff will do their best to help with Windows install issues!


"/usr/local" ownership errors:

El Capitan users will face this at some point, because the upgrade to El Capitan will change ownership of /usr/local (which Homebrew usually uses), to the root user. To fix this, just run:

chown -R $(whoami):admin /usr/local


"Missing module" error:

One way to debug if you get error messages of the form "No module named XXX" is to try installing XXX.  If you've gotten this far using pip, you can try using it in the same way to install these missing modules (for example module "XXX"):

pip install --user --upgrade XXX 

If this doesn't work, you can try looking online for how to install the missing module most easily on your specific system


Re-installing pip: 

If you installed pip via a package manager, and are having issues- or are just having issues in general- try re-installing / upgrading pip (via the instructions linked in Step 1 of the install post) first!


Python 2.7:

Ideally you are using this version- make sure you are not using Python 3; also specific distribution packages of python e.g. Anaconda may cause problems (see follow-up posts). The best way is to use Homebrew python!


On running as sudo:

If you have sudo access, and want to run the install commands as sudo, leave the "--user" flag out!


Distribute error:

If you get an error referencing the "Distribute" library and/or 'maximum recursion depth exceeded', you could try running "pip install --upgrade distribute" 


"Command ipython not found":

A lot of issues arise when IPython & other dependencies get installed correctly, but then the OS doesn't know where to find them.  When you type in a command such as "ipython notebook", your system looks for the "ipython" executable in all of the directories listed in your PATH environment variable.  You may need to add the directory where you installed IPython or pip to your PATH variable...


For example, if you successfully installed IPython but it's complaining that the command is not found, try adding ~/Library/Python/2.XXX/bin and ~/bin to your path (XXX = your version of python, probably 2.7) i.e. on Mac OS / linux, in your ~/.bash_profile or ~/.bashrc, add the line:

export PATH=${PATH}:~/Library/Python/2.XXX/bin:~/bin
  • Then after running that, you should be able to execute the command "which ipython" and have it show you where ipython is located
  • Note: you need to quite and restart your terminal in order for the bash_profile or bashrc to take effect


On Windows, add a directory to your PATH variable by following the steps in the first answer of this post


Also, try running "jupyter" instead of "ipython" and see if this solves your error ("Jupyter" is just IPython's recently re-branded name...).  E.g. in all commands such as 'ipython notebook' just replace "ipython" with "jupyter"


[FIXED] Incorrect dashes used in "--user": 

We've since corrected this, but if you copy-pasted directly from the install instructions, and got an error (something like a 'Missing Distribution Spec' error), note that we had the wrong style dashes in the instructions (sorry!)


Let us know if these suggestions are helpful!