How to version Jupyter notebooks: step by step guide

Introduction

This guide will show you how to:

  • Install neptune-notebook extension for Jupyter Notebook or JupyterLab

  • Connect Neptune to your Jupyter environment

  • Log your first notebook checkpoint to Neptune and see it in the UI

By the end of it, you will see your first notebook checkpoint in Neptune!

Before you start

Make sure you meet the following prerequisites before starting:

  • Have Python 3.x installed

  • Have Jupyter Notebook or JupyterLab installed

  • Have node.js installed if you are using JupyterLab

Step 1 - Install neptune-notebooks

Jupyter Notebook

To install neptune-notebooks on Jupyter Notebook:

  1. Install neptune-notebooks extension:

pip install neptune-notebooks
  1. Enable the extension for Jupyter Notebook:

jupyter nbextension enable --py neptune-notebooks

JupyterLab

To install neptune-notebooks on JupyterLab go to your terminal and run:

jupyter labextension install neptune-notebooks

Remember that you need to have node.js installed to use JupyterLab extensions.

Step 2 - Create some Notebook

Create a notebook with some analysis in it.

For example, you can use this code to create an interactive Altair chart of the cars dataset

Add installation command in the first cell

pip install altair vega_datasets

Create Altair chart in the second cell

import altair as alt
from vega_datasets import data
source = data.cars()
brush = alt.selection(type='interval')
points = alt.Chart(source).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q',
color=alt.condition(brush, 'Origin:N', alt.value('lightgray'))
).add_selection(
brush
)
bars = alt.Chart(source).mark_bar().encode(
y='Origin:N',
color='Origin:N',
x='count(Origin):Q'
).transform_filter(
brush
)
chart = points & bars
chart

Run both cells and see the interactive Altair visualization.

Step 3 - Configure Neptune API token

1) In Jupyter, click Connect to Neptune.

2) The Configure your connection to Neptune dialog appears.

2) Leave the dialog open and switch to the Neptune UI.

3) In the Neptune UI, obtain your API Token and copy it to the clipboard.

3.1) In the upper right corner, click the avatar, and then click Get API Token.

3.2) In the dialog that appears, click the Copy to clipboard button on the right. Then click Close.

4) Switch back to Jupyter. In the dialog you left open, paste the token you copied to the clipboard. Click Connect. A confirmation message is displayed. It contains a link through which you can go directly to this Notebook in Neptune.

Your API Token is private and unique. Never share it. It’s like sharing password.

See also

Step 4 - Save Notebook Checkpoint to Neptune

  1. Click on the Upload button.

You will be prompted to:

  • Choose which project you want to send this notebook to

  • Add a description of the notebook

Step 5 - See your notebook checkpoint in Neptune

Click on the green link that was created at the bottom of your notebook or go directly to the Notebooks section of your Neptune project.

Your notebook checkpoint was tracked and you can explore it now or later.

Conclusion

You’ve learned how to:

  • Install neptune-notebook extension for Jupyter Notebook or JupyterLab

  • Connect Neptune to your Jupyter environment

  • Log your first notebook checkpoint to Neptune and see it in the UI

What’s next

Now that you know how to save notebook checkpoints to Neptune you can learn: