2019-11-04·~2 mins read

Running Jupyter Notebook in Docker using pydockenv in 80 seconds

python

jupyter

docker

A closeup of Jupiter

Here's a video showing how I was able to do it in 80 seconds:

Cool right? And the only tools that you'll need are pydockenv and Docker of course.

But let's proceed in order.

What is pydockenv?

pydockenv is a project which is currently in alpha stage whose goal is to give the same experience of using virtual environments, but backed by Docker. So each python environment will actually correspond to a Docker container, and can be defined by using a .toml file. At time of writing it's compatible only with Python >=3.6.

For our purpose, we're actually only interested in how to install it and how to create the environment that will run our Jupyter Notebook. You can have a look at the home page of the project.

Installation

As explained in the README of the project, we can install pydockenv as follows:

The above command will install pydockenv to the Python user install directory to avoid conflicts. In order to run the pydockenv binary, you will need to have that directory in your PATH. You can do this by running these lines:

Now you have the pydockenv cli available!

Caveat

There's a little caveat: pydockenv assumes that the python binary runs Python >=3.6. In case that you have Python 3 available through python3, you should also run:

A look into the .toml file

As anticipated above, an environment can be defined using .toml file, that we will save as jupyter-notebook-env.toml. Here's its content:

If you're like: "Hey! Just let me run my Notebook!", then skip to the section "Let's run the Jupyter Notebook!", otherwise stay here to understand how the environment is defined.

A deeper dive into the .toml file

The first part it's actually almost self-explanatory:

This simply means that the name of the environment will be "jupyter-notebook-pydockenv" and that the correspdonding container will run Python 3.7.4.

The second part it's a sort of requirements.txt embedded into the this file. This simply lists all the requirements that will be installed inside the container:

In this case jupyter==1.0.0 is our only requirement.

Since the environment actually runs in a Docker container, this means that also all the commands will run inside that container. As you most probably know, to run a command insde a docker container you need to run:

and let's face it, it's not the most convenient thing to do.

So the third part simply defines an alias for running the Notebook:

Here an alias notebook is defined, and by running pydockenv run notebook we will actually run inside the container the command specified by cmd. The ports key is just a list of ports that the command requires to be opened on the container. If we do not open the specific port the Notebook will run, but it won't be accessible from the host.

Let's run the Jupyter Notebook!

And here we are!

Let's say that your project directory from where you want to run the Jupyter Notebook is in ~/Projects/awesome-project and that you already put the jupyter-notebook-env.toml inside. We have to create the environment from that directory:

Now, especially if you're used to virtual environments, you may ask: "Why the environment should bother about the directory from which I create it?". Well, that is because it runs in a Docker container, and what pydockenv does is to bind mount the project directory into the container. To be more specific it binds it into /usr/src.

The environment has been created! Let's activate it!

And we can now finally start our Notebook:

Conclusions

pydockenv is still at its beginning, but I'm actively working on it as I think that it has a lot of potential. If you liked it, don't forget to leave a 🌟 on Github and contributions are welcome! If you have ideas or find any issue, please leave a comment or open an issue.