JupyterLab and Jupyter Notebook

What will you get with this integration?
​JupyterLab and Jupyter Notebooks are popular IDEs used by data scientists for task such as data exploration, model training, error analysis, and reporting.
The Neptune-Jupyter integration lets you version, manage and share notebook checkpoints in your projects. Specifically, you can:
Log and display notebook checkpoints either manually or automatically during model training
Connect notebook checkpoints with model training Runs in Neptune
Organize checkpoints with names and descriptions 
Browse checkpoints history across all Notebooks in the project
Compare Notebooks side-by-side, with diffs for source, markdown, output, and execution count cells
Share Notebook checkpoints or diffs with persistent links​
Download Notebook checkpoints directly from the UI or Jupyter 
​See this notebook in Neptune​
The Neptune-Jupyter (neptune-notebooks) Python package includes:
The standard Jupyter extension. The extension is written in Javascript and is visible in the web-based Jupyter UI.
The JupyterLab extension. The extension is written in Javascript and is visible in the web-based Jupyter UI.
A very basic CLI (command line interface) for uploading notebooks.
Installation
Jupyter Notebook
Prerequisites
The following must be installed on your system:
Python 3.7+
​pip or conda​
​Jupyter​
Step 1: Install the neptune-notebooks extension:
pip
conda
pip install neptune-notebooks
conda install -c conda-forge neptune-notebooks
Step 2: Enable the extension for Jupyter:
jupyter nbextension enable --py neptune-notebooks
Step 3: Install the Neptune client library:
pip
conda
pip install neptune-client
conda install -c conda-forge neptune-client
JupyterLab
Prerequisites
The following must be installed on your system:
Python 3.6 +
​pip or conda​
​Node.js​
​npm​
​JupyterLab​
Installing through command line
This is the most complete installation of neptune-notebooks, which includes:
Extensions for both standard Jupyter and JupyterLab
CLI for uploading notebook files
The neptune-client package is a dependency
Step 1: On the command line, enter the following:
pip install neptune-notebooks
Step 2: Start JupyterLab:
jupyter lab
Step 3: In the “Build Recommended” notification that is displayed, click Build.
The build process takes up to several minutes.
Step 4: In the “Build Complete” notification that is displayed, click Reload.
Installing through JupyterLab Extension Manager
This installation doesn't include the command line interface (CLI) for managing notebooks and doesn't install neptune-client. 
Step 1: In JupyterLab, enable Extension Manager through Settings > Enable Extension Manager.
Step 2: Find "neptune-notebooks" and click Install.
Confirm successful installation
To confirm whether the neptune-notebooks extension was successfully installed:
1.Open a notebook
2.Check the top navigation of your notebook and verify that the Neptune functions have appeared: Neptune icon, Upload, Download, and Activate.
Configuration
After you have successfully installed the Jupyter extension for Neptune, connect it to your Neptune account.
Step 1: In Jupyter, click the Neptune icon.
The Configure your connection to Neptune dialog appears.
Step 2: Paste your Neptune API token and click Connect.
See how to get your Neptune API token from the Neptune UI. 
A confirmation message is displayed. It contains a link through which you can go directly to this Notebook checkpoint in Neptune.
Step 4: To see metadata logged from this notebook, you need to click Activate. 
When you restart the Jupyter kernel, your notebook checkpoints may not be saved to Neptune nor connected to the Neptune runs you created.
To fix that, you need to re-activate your notebook by clicking Activate in the Jupyter navigation.
Uploading notebook checkpoints
Upload notebook with a button
You can upload Notebook checkpoints from Jupyter to Neptune.
To upload the current notebook as a checkpoint:
Click Upload.
In the dialog that is displayed, select a project from the list.
(Optional) Type in a checkpoint name and description.
Click Upload checkpoint.
A confirmation message is displayed. You can click the link in the message to open the notebook in Neptune.
Auto-saving with neptune.init()
You can save notebook checkpoints automatically to Neptune whenever you create a Neptune run in a notebook cell.
To find notebook checkpoints connected to a Neptune run: In the run view, navigate to Source code > Notebook snapshot
To find Neptune runs that were created in a notebook: Navigate to the Notebooks tab, then select Details >  Runs.
To save a notebook checkpoint with every new Neptune run:
Step 1: Log the notebook to Neptune by clicking Upload in the Jupyter navigation. 
You have to manually log a notebook to Neptune before you create your first run. Otherwise, your run and notebook will not be connected.
After that, whenever you create a run, your notebook checkpoint will be logged automatically.
Step 2: Create a Neptune run:
Create a Neptune run in a notebook cell:
import neptune.new as neptune
​
run = neptune.init_run(
    api_token="ANONYMOUS",
    project="common/quickstarts",
)
Now, and with every future execution of a cell that contains neptune.init(), your notebook checkpoint gets uploaded to Neptune and connected to that Neptune run.
Step 3: View the notebook snapshot in the Neptune app.
In the run view, navigate to Source code > Notebook snapshot to find the notebook checkpoint associated with this run.
You can also find your notebook checkpoint in the Notebooks tab of the Neptune app. 
Displaying notebooks and checkpoints
The Notebooks tab in the Neptune app provides a table of all the notebooks in the current project.
This view lets you see what your team members are working on, review details and checkpoints associated with a notebook, as well as share or download a notebook and compare two or more notebooks.
Once you select a notebook, you can see all its contents including code and markdown cells, outputs, and execution count.
There are two tabs on the right:
Details: ID, size, creation date, latest checkpoint, owner, description, and associated runs of the selected notebook.
Checkpoints: all the checkpoints of the notebook. Click a checkpoint to see the details in the main pane. From this tab, you can also access the runs that are associated with the checkpoint.
Comparing checkpoints
The Notebooks Comparison pane lets you compare notebook checkpoints, including:
Code
Markdown
Cell output: with prints, visualizations, and other HTML outputs 
Execution count: order in which cells were executed
To compare notebook checkpoints: 
1.Select two notebook checkpoints.
2.Click Compare.
3.Explore the side-by-side comparison, just like source code.
Downloading checkpoints
You can download a specific notebook checkpoint from Neptune to Jupyter.
You can also download notebook checkpoints directly from the Neptune app. 
To download a notebook checkpoint from Jupyter:
In Jupyter Notebook, find the Neptune buttons in the top navigation.
Click Download.
In the dialog that is displayed, select Project, Notebook and Checkpoint.
Click Download.
Using Neptune CLI for notebooks
You can create notebooks and update notebook checkpoints in Neptune from the command line.
To do that, use the notebook sync command.
neptune notebook sync \
   --project workspace-name/project-name \
   your_notebook.ipynb
The notebook sync command lets you create new notebooks in Neptune or update existing ones with new checkpoints. 
We recommend using the neptune-notebooksJupyter extension whenever you can and only using the command line interface when necessary.
Setup
To use the CLI command, you must export your NEPTUNE_API_TOKEN as an environment variable. You can do this in either of two ways:
Execute this command:
Linux/macOS
Windows
export NEPTUNE_API_TOKEN='YOUR_LONG_API_TOKEN'
set NEPTUNE_API_TOKEN="YOUR_LONG_API_TOKEN"
Append the line above to your ~/.bashrc or ~/.bash_profile file.
Always keep your API token secret - it is like a password to the application. Appending the export NEPTUNE_API_TOKEN='YOUR_LONG_API_TOKEN' line to your ~/.bashrc or ~/.bash_profile file is the recommended method to ensure it remains secret.
Parameters
--project (optional)
Project to which to log notebook or checkpoint. If the NEPTUNE_PROJECT environment variable is set, this command overrides the environment variable.
--new (optional)
Takes the user’s notebook and creates a new notebook in Neptune.
If the notebook is not known to Neptune, it will be created. In this case, you do not need to use this flag.
neptune notebook sync \
   --project workspace-name/project-name \
   your_notebook.ipynb \
   --new
--update (optional)
Updates the user’s notebook in Neptune by adding a new checkpoint to it.
If the notebook is known to Neptune it will be updated. In this case, you do not need to use this flag.
neptune notebook sync \
   --project workspace-name/project-name \
   your_notebook.ipynb \
   --update
Getting help
Getting help
See also
Logging metadata
What can you log and display?
Querying and downloading metadata