neptune API reference

API reference for the neptune package and its functions.

You can use the global neptune object to initialize new Neptune objects or resume existing ones.

import neptune

init_project()

Starts a connection to an existing Neptune project. You can use it to fetch metadata of runs in the project.

You can also use the project object to manage metadata common to the whole project, such as information about datasets, links to documents, or key project metrics.

Parameters

To keep your token secure, avoid placing it in source code. Instead, save it as an environment variable.

If you leave it out, the value of the NEPTUNE_MODE environment variable is used. If that's not set, the default async is used.

Note: Instead of using this argument, you can use Neptune's default callback by setting the NEPTUNE_ENABLE_DEFAULT_ASYNC_LAG_CALLBACK environment variable to TRUE.

Note: Instead of using this argument, you can use Neptune's default callback by setting the NEPTUNE_ENABLE_DEFAULT_ASYNC_NO_PROGRESS_CALLBACK environment variable to TRUE.

The name parameter was changed to project in neptune-client 0.16.16.

Returns

Projectobject that can be used to interact with the project as a whole, like logging or fetching project-level metadata.

Example

Connect to the project "classification" in the workspace "ml-team":

import neptune

project = neptune.init_project(project="ml-team/classification")

project["general/data_analysis"].upload("data_analysis.ipynb")

Theprojectobject follows the same logic as other Neptune objects: If you assign a new value to an existing field, the new value overwrites the previous one.

In a given project, you always initialize and work with the sameprojectobject, so take care not to accidentally overwrite each other's entries if your team is collaborating on project metadata.

Tip

Recall that theappend()method appends the logged value to a series. It works for text strings as well as numerical values.

Connect to a project in read-only mode:

project = neptune.init_project(
 project="ml-team/classification",
 mode="read-only",
)

init_run()

Starts a new tracked run and adds it to the top of the experiments table.

Since all parameters are optional, the minimal invocation is:

import neptune

run = neptune.init_run()

See also: Defining a custom init_run() function, for keeping the logging consistent within your team.

If you initialize a run in an interactive session (Python interpreter or Jupyter Notebook), the following monitoring options are disabled by default:

• capture_stdout
• capture_hardware_metrics

To enable them, set each parameter to True when initializing the run. Note: The monitoring will continue until you call run.stop() or the kernel stops.

Also note: Your source files can only be tracked if you pass the path(s) to the source_code argument. For help, see Logging source code.

Parameters

To keep your token secure, avoid placing it in source code. Instead,save it as an environment variable.

If you leave it out, the value of theNEPTUNE_MODEenvironment variable is used. If that's not set, the defaultasyncis used.

List of source files to be uploaded. Must be list ofstror a singlestr. Uploaded sources are displayed in theSource codesection of the run.

IfNoneis passed, the Python file from which the run was created will be uploaded. When resuming a run, no file will be uploaded by default. Pass an empty list ([]) to upload no files.

Unix style pathname pattern expansion is supported. For example, you can pass".py"to upload all Python source files from the current directory. Paths of uploaded files are resolved relative to the calculated common root of all uploaded source files. For recursion lookup, use"**/.py"(for Python3.5and later). For details, see thegloblibrary.

IfNone, Neptune looks for a repository in the path of the script that is executed.

To specify a different location, set toGitRef(repository_path="path/to/repo").

To turn off Git tracking for the run, set toGitRef.DISABLEDorFalse.

Note:Instead of using this argument, you can use Neptune's default callback by setting theNEPTUNE_ENABLE_DEFAULT_ASYNC_LAG_CALLBACKenvironment variable toTRUE.

Note:Instead of using this argument, you can use Neptune's default callback by setting theNEPTUNE_ENABLE_DEFAULT_ASYNC_NO_PROGRESS_CALLBACKenvironment variable toTRUE.

Therunparameter was changed towith_idin neptune-client0.16.7.

Returns

Runobject that is used to manage the tracked run and log metadata to it.

Examples

Create a new run:

import neptune

run = neptune.init_run()

Create a run with a custom name:

run = neptune.init_run(name="timid-bramble")

Create a run with:

• a name and description
• custom monitoring namespace (recommended)
• no sources files or Git info uploaded

run = neptune.init_run(
 name="jolly-butter",
 description="neural net trained on MNIST",
 monitoring_namespace="monitoring",
 source_files=[],
 git_ref=False,
)

Resume an existing run, to continue logging to it:

import neptune

run = neptune.init_run(with_id="CLAS-134")

run["namespace/field"] = some_metadata
...

The Neptune ID is a unique identifier for the run. TheExperimentstab displays it in the leftmost column.

In the run structure, the ID is stored in the system namespace (sys).

• If the run is active, you can obtain its ID withrun["sys/id"].fetch(). For example: >>>run=neptune.init_run()...>>>run["sys/id"].fetch()'CLS-26'
• If you set a custom run ID, it's stored atsys/custom_run_id: >>>run["sys/custom_run_id"].fetch()'vigilant-puffin-20bt9'

If the run is active, you can obtain its ID withrun["sys/id"].fetch(). For example:

>>> run = neptune.init_run()
...
>>> run["sys/id"].fetch()
'CLS-26'

If you set a custom run ID, it's stored atsys/custom_run_id:

>>> run["sys/custom_run_id"].fetch()
'vigilant-puffin-20bt9'

Resume a run in read-only mode, to only read metadata from it:

run = neptune.init_run(with_id="CLAS-134", mode="read-only")

run["train/model_weights"].download()

Resume a run in order todelete data:

run = neptune.init_run(
 with_id="CLAS-134",
 capture_hardware_metrics=False,
 capture_stderr=False,
 capture_stdout=False,
 capture_traceback=False,
 git_ref=False,
 source_code=[],
)

del run["namespace"]

Start a new run and log all Python files in the current working directory (excluding hidden files with names beginning with a dot):

run = neptune.init_run(source_files="*.py")

Log all Python files from all subdirectories (excluding hidden files):

run = neptune.init_run(source_files="**/*.py")

Log all files and directories in the current working directory (excluding hidden files):

run = neptune.init_run(source_files="*")

Log all files and directories in the current working directory, including hidden files

run = neptune.init_run(source_files=["*", ".*"])

Larger example:

run = neptune.init_run(
 name="first-pytorch-ever",
 description="Write a longer description here.",
 tags=["pytorch", "test", "do-not-delete"],
 source_files=["training_with_pytorch.py", "net.py"],
 capture_hardware_metrics=False,
 dependencies="infer",
)

While it's not a recommended practice, you can also pass your Neptune credentials in the code when initializing Neptune.

run = neptune.init_run(
 project="ml-team/classification", # your full project name here
 api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jvYh3Kb8", # your API token here
)

Set your Neptune API token and full project name to theNEPTUNE_API_TOKENandNEPTUNE_PROJECTenvironment variables, respectively.

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

export NEPTUNE_PROJECT="ml-team/classification"

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

export NEPTUNE_PROJECT="ml-team/classification"

setx NEPTUNE_API_TOKEN "h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

setx NEPTUNE_PROJECT "ml-team/classification"

You can also navigate toSettings→Edit the system environment variablesand add the variables there.

%env NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

%env NEPTUNE_PROJECT="ml-team/classification"

To find your credentials:

• API token : In the bottom-left corner of the Neptune app, expand your user menu and select Get your API token . If you need the token of a service account, go to the workspace or project settings and enter the Service accounts settings.
• Project name : Your full project name has the form workspace-name/project-name . You can copy it from the project menu ( → Details & privacy ).

If you're working in Google Colab, you can set your credentials with the os and getpass libraries:

import os
from getpass import getpass
os.environ["NEPTUNE_API_TOKEN"] = getpass("Enter your Neptune API token: ")
os.environ["NEPTUNE_PROJECT"] = "workspace-name/project-name"

ANONYMOUS_API_TOKEN

API token for anonymous logging.

You can use this value for theapi_tokenargument of theinitfunctions.

Example

Start a run as an anonymous user:

import neptune

run = neptune.init_run(
 api_token=neptune.ANONYMOUS_API_TOKEN,
 project="common/quickstarts",
)

If you're not using a function from theneptunepackage to initialize Neptune, you can also import and use the anonymous API token separately.

from pytorch_lightning import Trainer
from pytorch_lightning.loggers import NeptuneLogger

from neptune import ANONYMOUS_API_TOKEN

neptune_logger = NeptuneLogger(
 api_key=ANONYMOUS_API_TOKEN, 
 project=...,
)

Related Documentation

• Run API
• Project API

This page is originally sourced from the legacy docs.