Jupyter Notebooks container in VSCode

This post describes how to setup the VSCode IDE to work with Jupyter Notebooks inside a Docker container.

TL;DR

I’ve created a VScode template project that supports Jupyter development inside a Docker container. It includes some improvement on the notebook export functionality with respect to other similar projects I’ve found online. It is available on GitHub (checkout the branch named custom).

Setup

First things first, make sure Docker is installed on your system; on Linux this can be done with the following command:

sudo apt-get install docker-ce

Next, go ahead download and install Visual Studio Code from the official page and once it’s done make sure to add the following extensions:

  • Dev Containers extension lets you use a Docker container as a full-featured development environment
  • Jupyter extension, provides basic notebook support for language kernels that are supported in Jupyter Notebooks today, and allows any Python environment to be used as a Jupyter kernel.

Dev Containers

As it does for other IDE features, VScode offers a mechanism to have container-related settings configured and persisted in a .json file. A Dev Containers-aware folder/workspace only needs a .devcontainer folder with two files in it:

  • devcontainer.json which contains any needed metadata and settings required to configurate a development container for a given well-defined tool and runtime stack
  • Dockerfile a text document that contains all the commands a user could call on the command line to assemble a Docker image

Basically, the Dev Containers take an existing Dockerfile, fully compatible with standard Docker, and add some metadata to better integrate it in a typical VSCode development workflow e.g., launching Docker in the background, hiding away some mundane tasks, automate some others and most important let you focus on the development that really matters.

As most of the times happens these days we can avoid writing our Dev Container from scratch and get inspired by some of the existing ones. In the particular case of Jupyter, the jupyter-devbox project is an excellent starting point.

Jupyter Devbox

The jupyter-devbox is a project that wraps most of what described above in a ready-to-use folder that comes with a Dockerfile tailored to machine learning and computer vision development.

Instead of cloning the original repo I worked on my own and made some changes, available on GitHub.

Customizations

Things I’ve changed from the original jupyter-devbox are:

  • removed machine learning and computer vision packages
  • added pandoc to export notebooks to non-HTML formats
  • added texlive to export notebooks to PDF format
  • added Python packages to work with .xlsx and InfluxDB

Check them out in the new Dockerfile

Jupyter notebook export

On top of the customizations described above, I’ve added .vscode/tasks.json to leverage the automation exposed by the VSCode Tasks framework.

In my case I wanted to have quick access to converting and exporting the current notebook, so I’ve added few custom tasks like so:

"tasks": [
    {
        "label": "New Task",
        "type": "shell",
        "group": "build",
        "command": "jupyter-nbconvert",
        "args": [
            "--to", "pdf",
            "--TemplateExporter.exclude_input", "True",
            "${file}"
        ],
    }
]

More custom tasks can be added simply appending more of the same blocks to the tasks.json file.

TODOs and Further development

Few ideas I’d like to experiment with in the future are:

  • implement a different Dockerfile that the one from jupyter-devbox, for example creating my own Dockerfile starting from the Jupyter Docker Stacks.
  • write a VSCode extension to have additional commands and shortcuts in a contextual menu (i.e., right-clicking on a notebook file in the VSCode file explorer)

References

Here’s a list of some of the references used throughout this project:

You May Also Enjoy

Buildroot basics

Some of the most useful takeaways from the Buildroot official manual.