Classic Jupyter Notebook Branding Hack

Noting that another OU module has just started using classic Jupyter notebooks, with a deployment route based on students creating a miniconda environment, installing the notebook server and an additional R-kernel, into that environment, and then running the Jupyter notebook server from that environment, I tried a quick hack to package up a simple Pyhton extension to brand the notebook server.

The trick I use for branding our deployed environments is simply to use a custom logo and custom stylesheet. These need placing in a custom directory on the Jupyer server environment path. Getting the files in the correct place caused some issues, notably:

  • the jupyter_core package, in a recent version, has various routes to finding Jupyter config directories via jupyter_core.paths. But older versions don’t seem to support that, so updating jupyter_core simply to add a logo feels a bit risky to me;
  • getting the path to the environment is a faff, and can be sensitive to the ennvironment in which you run the jupyter --paths commands to discover paths. The hack I came up with was by default to install into the “generic” ~/.jupyter path, with an option to pass in a conda environment name and then try to find a path that relates to that (and so far, only tested on a Mac).

Anyway, the repo is currently at and can be installed as

pip install --upgrade  git+

ou_nb_branding install --conda ENVIRONMENT_NAME

The ENVIRONMENT_NAME is the name of the conda envt you want to install into if you installed and are running the jupyter server in the env. In M348 defaults , this means running the following command before you start the jupyter server:

ou_nb_branding install --conda r_env

Getting the path to install into is a hack, so it may break (plus, I only tested on Mac).

Without the --conda switch, the installation defaults to whatever home Jupyter environment path is found. So in a simple envt installing the custom branding to default path, just run: ou_nb_branding install

For branding JupyterLab (and I have no idea if this works for retrolab/new notebook etc.), see

Author: Tony Hirst

I'm a Senior Lecturer at The Open University, with an interest in #opendata policy and practice, as well as general web tinkering...

%d bloggers like this: