Collaborating with Jupyter notebooks


Jupyter notebooks are documents that enable the recording and sharing of computational ideas. Often, such ideas are developed and shared by teams of people, distributed throughout the world, collaborating in multiple ways at multiple time scales. Sometimes one person makes changes and proposes them to the project via a version control system such as git, which we can call “long-term collaboration”. At other points during the work, contributors may want to work together on the document at the same time, which we call “real-time collaboration.” Collaboration is a key part of the development and dissemination of computational ideas, so it is important for Jupyter notebooks to be well suited to these tasks.


Ash and Fatima are collaborating on a project. They have developed a model, and have some demonstrations to run, illustrating how their model works, and running it through some sample tasks with visualisations. Fatima has some changes to make to the demonstration and would like Ash’s feedback.

For this, Ash needs to:

Ash reviews Fatima’s changes and would like to discuss them further, iterating on the changes to come to a conclusion that both can agree on.

For this second part, Ash and Fatima need to:

Suggestion of solution

  1. They use a Jupyter notebook for the demonstration of the model, to encapsulate prose, code, and outputs in one place.
  2. They publish the work as a git repository, enabling review of changes step-by-step as they are made.
  3. Ash uses nbdime to review Fatima’s changes in the repository.
  4. They use nbval to validate each change to notebooks via Continuous Integration service such as TravisCI.
  5. Ash and Fatima use JupyterLab for real-time collaboration to work through rapid feedback and come to a resolution.


By using Jupyter notebooks, the illustration of the model can be a single container for prose explanation, implementation in code, and visualisations of results. Further, it can be shared as an interactive document for others to download, execute, and modify, either in their own environments, or online with zero installation via services such as Binder.

Time and expertise required

Assuming the team is familiar with version control and Jupyter (basic lab skills taught at Software Carpentry, and is fluent in using Jupyter notebook, the initial setup of the collaboration could be done in a few minutes. For live collaboration, a notebook server to which both contributors can connect would need to exist. JupyterHub can be used for this, or for short-term collaboration, may be used with zero installation.

What’s new since OpenDreamKit started

OpenDreamKit contribution

Jupyter Use Cases Open Science and Reproducibility Reproducibility Best Practice