neptune-ai/neptune-notebooks

📚 Jupyter Notebooks extension for versioning, managing and sharing notebook checkpoints in your machine learning and data science projects.

Neptune-Jupyter integration

Neptune is a lightweight experiment tracker that offers a single place to track, compare, store, and collaborate on experiments and models.

The Neptune-Jupyter extension lets you version, manage, and share notebook checkpoints in your projects.

Note: The extension currently works for JupyterLab <4.0.

What will you get with this integration?

• 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 Neptune or Jupyter

Resources

• Documentation
• Example notebook in Neptune

Setup

Install the extension:

pip install neptune-notebooks

Enable the extension for Jupyter:

jupyter nbextension enable --py neptune-notebooks

In your Jupyter Notebook environment, some Neptune items appear in your toolbar.

1. To connect with Neptune, click the Neptune Configure button.
2. Enter your Neptune credentials.
3. To register the notebook in Neptune, click Upload.

This uploads a first checkpoint of the notebook. Every time you start a Neptune run in the notebook, a checkpoint is uploaded automatically.

For detailed instructions, see the Neptune documentation.

Usage

In a notebook cell, import neptune and start a run:

import neptune

run = neptune.init_run()

Log model-building metadata that you care about:

run["f1_score"] = 0.66

For what else you can track, see What you can log and display in the Neptune docs.

When you're done with the logging, stop the run:

run.stop()

You can view the notebook snapshot in the run's Source code dashboard or the project's Notebooks section.

Support

If you got stuck or simply want to talk to us, here are your options:

• Check our FAQ page
• You can submit bug reports, feature requests, or contributions directly to this repository
• Chat! When in the Neptune application click on the blue message icon in the bottom-right corner and send a message. A real person will talk to you ASAP (typically very ASAP)
• You can just shoot us an email at [email protected]

neptune-notebooks's Issues

Feature request: automatic integration

What I want

Not having to integrate every new notebook.

My suggestion

Add a setting to automatically integrate the notebook with Neptune at startup.

My current workaround

No workaround yet. I have to hack some JS in https://github.com/neptune-ml/neptune-notebooks/blob/master/packages/nbextension/neptune-notebook.js to automatically call createNotebook together with #30

Feature request: load API token from the Jupyter server

What I want

Not having to enter the API key for every new notebook. This critically complicates the usage of the "magic button" in a team of 10 people with Jupyter in Kubernetes (read: they refuse to participate in the mess).

What I suggest

Provide a way to retrieve the API key from the Jupyter server. It could be loaded from NEPTUNE_API_TOKEN environment variable defined by Helm, from the FS or through LDAP or whatever else.
Currently, it is loaded from the browser local storage only.

My workaround

I hack my Dockerfile to load the API key when Jupyter starts and insert it at
https://github.com/neptune-ml/neptune-notebooks/blob/master/packages/nbextension/neptune-notebook.js#L451 instead of the empty default ''. I overwrite the JS file, which is soooo hacky.

Hyperlink in Jupyterlab links to 404

It links to https://github.com/neptune.ml/neptune-notebooks.
Just change neptune.ml to neptune-ml and it'll be fine.

Cannot enable Neptune notebook extension on Google Colab notebook

I want to use Neptune Jupyter notebook extension in Google Colab notebook.

! pip install neptune-client neptune-contrib neptune-notebooks
! jupyter nbextension enable --py neptune-notebooks
Requirement already satisfied: neptune-client in /usr/local/lib/python3.7/dist-packages (0.9.16)
Requirement already satisfied: neptune-contrib in /usr/local/lib/python3.7/dist-packages (0.27.1)
Requirement already satisfied: neptune-notebooks in /usr/local/lib/python3.7/dist-packages (0.9.0)

The "neptune-client" itself work well, I just cannot enable Jupyter notebook extension. The following error is thrown when executing the "jupyter nbextension enable" line:

Traceback (most recent call last):
  File "/usr/local/bin/jupyter-nbextension", line 8, in <module>
    sys.exit(main())
  File "/usr/local/lib/python2.7/dist-packages/jupyter_core/application.py", line 267, in launch_instance
    return super(JupyterApp, cls).launch_instance(argv=argv, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/traitlets/config/application.py", line 658, in launch_instance
    app.start()
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 988, in start
    super(NBExtensionApp, self).start()
  File "/usr/local/lib/python2.7/dist-packages/jupyter_core/application.py", line 256, in start
    self.subapp.start()
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 896, in start
    self.toggle_nbextension_python(self.extra_args[0])
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 872, in toggle_nbextension_python
    logger=self.log)
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 483, in enable_nbextension_python
    logger=logger)
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 380, in _set_nbextension_state_python
    m, nbexts = _get_nbextension_metadata(module)
  File "/usr/local/lib/python2.7/dist-packages/notebook/nbextensions.py", line 1122, in _get_nbextension_metadata
    m = import_item(module)
  File "/usr/local/lib/python2.7/dist-packages/traitlets/utils/importstring.py", line 42, in import_item
    return __import__(parts[0])
ImportError: No module named neptune-notebooks

`neptune-notebooks` does not work with `jupyterlab>=4.0`

when I use nuptune-notebook in Jupyter-lab , I find this warning:

[W 2023-07-03 18:29:18.653 LabApp] The extension "neptune-notebooks" is outdated.

but it not come out in jupyter notebook, why? could you help me answer this question.

papermill & batch integration/compatibility?

For my work, I run experiments as batch jobs on a HPC cluster using papermill (https://papermill.readthedocs.io/en/latest/) to execute ipython/jupyter notebooks, inside the notebooks I use the neptune client to upload metrics and artifacts.

I would also like the output notebooks from papermill to be usable within the neptune website ui, and to automatically log the checkpoints and such so I can remotely monitor a job or review the notebook after the job has completed without needing to ssh into the cluster again.

I haven't updated to the newer neptune api client yet, or to newer versions of this project, but is it possible currently to use the notebook plugin to automatically upload the notebooks in a batch-mode manner? I looked at the docs and there maybe a mechanism to use the CLI inside/outside the notebook to do this, but there appears to be a focus on the "interactive" use case when a user is using jupyter/jupyter lab inside a browser and has access to the UI.

Currently I am going to try a work-around that just uploads the notebook using log_artifact from the legacy API in the last cell of the notebook, but that is not a great solution as the neptune website likely won't render the notebook in the browser.

Ideally, I would like either this plugin or the neptune client to know (or be provided a path to) a notebook during runtime and not need to worry about anything else, it just isn't clear from the docs if that is the case now with the newer versions of the client and this project, or not.