Run Jupyter notebook server in Docker
Running your Jupyter notebooks from Docker means you can easily recreate your environment on another computer.
When you’re executing several long running jobs, you can sneakily run an additional server on a co-workers machine!
If you are new to Docker, you can checkout my introduction to docker, as this tutorial will skip the basics. I have included the complete Dockerfile at the bottom of the post in case you don’t want to read the step by step instructions.
Installing Jupyter with pip
First I am going to show you a basic Jupyter setup. For this we are going to install Jupyter notebook, NumPy, SciPy, Pandas, Scikit-learn and Matplotlib.
FROM ubuntu:16.04
RUN apt-get update \
&& apt-get install -y python-pip build-essential \
&& apt-get -y autoremove \
&& apt-get -y clean \
&& rm -rf /var/lib/apt/lists/*
RUN pip install pip -U \
&& pip install jupyter numpy scipy pandas sklearn matplotlib \
&& rm -r /root/.cache/pip
CMD jupyter-notebook --ip="*" --no-browser
The first line states which base image you want to start from, in this case I’ve chosen Ubuntu 16.04 Xenial Xerus. The second command (starting with RUN
) installs pip
and build-essential
which is a set of tools that are commonly required for installing software from source. The additional lines in this RUN
command clean up any excess data that was added to the image due to using apt
.
The second RUN
command updates pip and installs the required pip packages. The final part of this statement removes the pip cache to reduce the size of the image.
The CMD
line launches the Jupyter notebook server. The server will be accessed from outside of the container, which is why you wantt to allow all IP addresses to connect, and don’t want to launch a browser.
To build and run the container, you can use the following commands.
docker build -t <imagename> .
docker run -ti -v /your/notebook/directory:/notebooks -p 7777:8888 <imagename>
Replace /your/notebook/directory
with your local (host) notebook directory, this will then be mounted at /notebooks/
within the container.
Following this you will be able to access Jupyter by navigating to localhost:7777
in your browser.
Installing the same packages as your current environment
There is a shortcut to install the same packages and package versions you currently have installed in your development environment (provided you use pip for package installation). If you run pip freeze
in the command line this outputs a list of installed packages and their version numbers, which will look something like this:
numpy==1.11.2
pandas==0.19.0
...
If you write that to a requirements file (pip freeze > requirements.txt
), and put it in the same directory as the Dockerfile. We can swap the pip RUN command for the following and now all of your previous pip install commands will be replicated in the container.
# copy across pip files
COPY requirements.txt /requirements.txt
# install python packages
RUN pip install pip -U \
&& pip install -r /requirements.txt \
&& rm -r /root/.cache/pip
Install Jupyter extensions
I wrote a post on Jupyter extensions here, and this is how to add them to out Jupyter Docker container.
We need to add additional package jupyter_contrib_nbextensions
to the pip list from before as shown below, and need to add an additional line to activate the extensions.
RUN pip install pip -U \
&& pip install jupyter numpy scipy pandas sklearn matplotlib \
&& pip install jupyter_contrib_nbextensions \
&& rm -r /root/.cache/pip
RUN jupyter contrib nbextension install
If you want to copy across your existing notebook extension settings, they are stored in ~/.jupyter/nbconfig/notebook.json
. You can see an example starting point in my other post. If you copy that file into the same directory as your Dockerfile, and add the line below, the config file will be copied into your container and loaded into Jupyter.
COPY notebook.json /root/.jupyter/nbconfig/notebook.json
Complete Dockerfile
Now you know how to create a Docker container to run Jupyter notebooks. To make things easier, I’ve included a complete Dockerfile below. This file assumes that you have written a requirements.txt file, and that your directory contains a notebook.json
config file.
FROM ubuntu:16.04
RUN apt-get update \
&& apt-get install -y python-pip build-essential \
&& apt-get -y autoremove \
&& apt-get -y clean \
&& rm -rf /var/lib/apt/lists/*
RUN pip install pip -U \
&& pip install -r /requirements.txt \
&& pip install jupyter_contrib_nbextensions \
&& rm -r /root/.cache/pip
RUN jupyter contrib nbextension install
COPY notebook.json /root/.jupyter/nbconfig/notebook.json
CMD jupyter-notebook --ip="*" --no-browser