CODEX

How to do a clean setup of Jupyter notebook on Mac using Docker

Easy way to setup Jupyter notebook on your Mac in under 3 minutes using Docker

Photo by Clay Banks on Unsplash

If you have already tried to install Jupyter notebook on your Mac then it is very likely you faced issues with a virtual environment or workarounds intended to use Python 3 instead of default Python 2.

Let me relieve your mind and show you an easier way to do it.

If you are willing to quickly set up all things first — go to the Summary section and follow the instructions described there. For those who want to understand what we are going to do and discover some tips for efficient Jupyter usage — lean back on your chair and continue reading. In general, it is preferable to understand everything about what you are running on your machine. You never know what strangers want to do with your Mac (just joking).

Docker

I know I promised to help you to set up the Jupyter book on your Mac, but we need to start from Docker because it is a magic tool that will do all these for you. You can read the “official” definition, but I will try to put it in plain language.

Docker launches applications on your computer, without the need of installing all things directly to your system. It creates a virtual environment with all packages and dependencies that are needed for applications. Also, using Docker, you control how much of your computer’s resources are allocated to the application.

There are two main concepts that you need to understand: image and container.

An image is a combination of system files with required languages, libraries, and other dependencies placed all together into a single file. You can download various docker images from Docker Hub, which is similar to GitHub, where people store images instead of code.

A container is a running environment based on the image you specify. Each container has resources allocated to it: e.g. the amount of memory, number of CPUs. You can create several containers running at the same time based on the same image.

It means that when you download an image and run it — you can do whatever you like within the running environment. If you screwed up something, you can always start again by deleting the container and running the new one. It is really convenient because your Mac remains clean.

You can install the Docker app to your Mac using instructions.

Download image

Having installed Docker, we come to the most interesting part — choosing the image of the Jupyter notebook that will suit your needs.

There are many Jupyter images, depending on the variety of Python libraries installed and the additional setup of R and/or PySpark. You can check them all on the official website, but to make it easier I brought a comparison diagram here.

Diagram by Jupyter on Jupyter Docker Stacks (Open source license usage)

Every consequent image on the diagram is based on the previous one. So for example scipy-notebook image contains everything from the minimal-notebook image, which, in turn, contains everything from the base-notebook. If you don’t know which one to choose — don’t worry, you can install the base one and then install all the needed packages with pip on top of it.

I personally use scipy-notebook, which contains most of the basic data science libraries that I need. It contains dask, pandas, numexpr, matplotlib, scipy, seaborn, scikit-learn, scikit-image, sympy, cython, patsy, statsmodel, cloudpickle, dill, numba, bokeh, sqlalchemy, hdf5, vincent, beautifulsoup, protobuf, xlrd, bottleneck, and pytables packages.

I think it covers pretty much everything you might need. Moreover, the scipy-notebook image contains ipywidgets and ipympl for interactive visualizations and facets for visualizing machine learning datasets.

To download the image, start Docker and run the following command in your terminal:

docker image pull jupyter/scipy-notebook

In case you would like to try another image, do not forget to replace scipy-notebook with the name of the image you like. It will pull the latest version of it to your Docker app and it will appear in the Image tab.

Launch container

After you downloaded your image — it is time to launch the container, it can be done with the following command.

docker container run --name jupyter -p 8888:8888 -v <local_path>:/home/jovyan/ jupyter/scipy-notebook

Let’s see in details what is written in this command:

docker container run speaks for itself. It creates a container from the image.

--name jupyter provides a name for our container. In this way, we can refer to it instead of a long technical name.

-p 8888:8888 indicates which ports will be used for communication between the container and your system. As Jupyter is a web-based application, you need to tell the system which port will be assigned to it.

-v <local_path>:/home/jovyan/ defines which folder from your computer should be mounted to the container. Usually, this is a folder with project working files. Don't forget to replace <local_path> and with your path. For example, I have project files on my desktop and I would use /Users/ann/Desktop/ds_project.

After that, you should see your Docker container running in the Containers/Apps tab.

To find Jupyter notebook URL, click on the container and copy the URL from the Docker logs afterward Or copy and paste one of these URLs:

Screenshot by the author

Congratulations! That's it — you can enjoy Jupyter notebook on your Mac.

To install additional packages, you could go into the container by running the following command in the terminal:

docker container exec -it jupyter bash

When you are inside, you can run the usual pip install commands.

Also, in the Docker application, in the Settings/Resources tab, you can specify the max amount of CPUs and memory that will be used by your container.

Bonus: Productivity tips

Sometimes people complain that Jupyter notebooks lack functionality and are not that comfortable to use. That’s true only for the most basic notebooks. But you even the odds adding extensions. The whole list of extensions can be found here and I prepared a brief overview of the extensions I mostly use.

Extensions can be installed using the following command launched inside the docker container.

pip install jupyter_contrib_nbextensions && jupyter contrib nbextension install --user

After installation, you should stop and launch the container again to see a new tab with extensions in Jupyter.

Screenshot by the author

If you delete your container extensions also will be deleted.

Spellchecker

Spellchecker checks to spell in your markdown cells. This is enormously helpful because sometimes it is hard to notice typos. You do not need to install additional packages to make it work, only to mark the checkbox in the extensions tab.

Hide Input

Do you want to hide blocks of code to see only markdown and results in your book? Hide Input extension will help you to do this, but you need to mark its checkbox in the extensions tab.

Hinterland

Hinterland will enable a code autocompletion menu like in popular IDEs, like PyCharm, and it provides pretty the same functionality: you type several characters and get a drop-down list with all possible autocompletion options. Just like with previous extensions — you need to mark the checkbox in the extensions tab.

Table of Contents (2)

This extension creates a table of content for your notebook based on headers in markdown cells and allows you to click on the specific item to go to this part of the notebook. It comes in handy when your notebook becomes so large that you can spend several minutes to find the desired part of the analysis.

Variable Inspector

This extension collects all defined variables and displays them in a separate floating window. It becomes useful when you want to check the value of some variable, but do not want to go and print it somewhere or search where it is already printed.

Autopep8

The name speaks for itself: when you click on this extension button it reformats/prettifies the contents of the code cell.

Summary

To install and run scipy-notebook version of Jupyter notebook on your Mac you should:

1. Install Docker app using this guide
2. Download image with Jupyter notebook
   docker pull jupyter/scipy-notebook
3. Launch the container, replacing <local_path>with the path to your project folder
   docker container run --name jupyter -p 8888:8888 -v <local_path>:/home/jovyan/ jupyter/scipy-notebook
4. Copy URL from the Docker logs to the browser

Screenshot by the author

I do hope it was helpful, please let me know if you spot any mistakes in the comments.