How to connect Neptune to your codebase step by step

Adding Neptune is a simple process that only takes a few steps. We’ll go through those one by one.


This guide will show you how to:

  • Connect Neptune to your script from scratch

  • Find ML framework integrations to start tracking your runs with even less work

  • Find tracking tool integrations to sync/convert experiment information from your current tool to Neptune experiments

By the end of it, you will have experiments from your project logged and versioned in Neptune!

Before you start

Make sure you meet the following prerequisites before starting:

Step 1: Are you using Python? Choose your client library

Neptune was built for Python first and if this is your language of choice jump to the next Step!

If you are not using Python, no worries, Neptune plays nicely with other languages as well.

Read how to use Neptune with other languages here.

Step 2: See if Neptune integrates with your current experiment tracking tool (Optional)

Neptune has utilities that let you use other open-source experiment tracking tools together with Neptune They also make the migration from those tools easy and quick.

Neptune integrates with the following experiment tracking frameworks:

Step 3: See if Neptune integrates with your ML framework (Optional)

Neptune supports any machine learning framework but there are a lot of integrations with particular frameworks that will get you started faster.

Machine learning frameworks:

Hyperparameter Optimization frameworks:

Check out the full list of integrations.

Step 4: Add Neptune logging explicitly

You can always add Neptune logging into your codebase explicitly.

Let me show you how to do that step by step.

  1. Connect Neptune to your script

import neptune


You need to tell Neptune who you are and where you want to log things.

To do that you should specify:

  • project_qualified_name=USERNAME/PROJECT_NAME: Neptune username and project

  • api_token=YOUR_API_TOKEN: your Neptune API token.


If you followed suggested prerequisites:

You can skip api_token and change the project_qualified_name to your USERNAME and PROJECT_NAME

  1. Create an experiment and log parameters

PARAMS = {'lr': 0.1, 'epoch_nr': 10, 'batch_size': 32}
neptune.create_experiment(name='great-idea', params=PARAMS)

This opens a new “experiment” namespace in Neptune to which you can log various objects. It also logs your PARAMS dictionary with all the parameters that you want to keep track of.


Right now parameters can only be passed at experiment creation.


You may want to read our article on:

  1. Add logging of training metrics

neptune.log_metric('loss', 0.26)

The first argument is the name of the log. You can have one or multiple log names (like ‘acc’, ‘f1_score’, ‘log-loss’, ‘test-acc’). The second argument is the value of the log.

Typically during training there will be some sort of a loop where those losses are logged. You can simply call neptune.log_metric multiple times on the same log name to log it at each step.

for i in range(epochs):
    neptune.log_metric('loss', loss)
    neptune.log_metric('metric', accuracy)


You can specifically log value at given step by using x and y arguments.

neptune.log_metric('loss', x=12, y=0.32)
  1. Add logging of test metrics

neptune.log_metric('test-accuracy', 0.82)

You can log metrics in the same way after the training loop is done.


You can also update experiments after the script is done running.

Read about updating existing experiments.

  1. Add logging of performance charts

neptune.log_image('predictions', 'pred_img.png')
neptune.log_image('performance charts', fig)


There are many other object that you can log to Neptune. You may want to read our articles on:

  1. Add logging of model binary


You save your model to a file and log that file to Neptune.


There is a helper function in neptune-contrib called log pickle for logging picklable Python objects without saving them to disk.

It works like this:

from neptunecontrib.api import log_pickle


Run your script and see your experiment in Neptune UI