Skip to content

neptune API reference#

Info

Neptune object types are: Run, Model, ModelVersion, and Project.

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

It also provides some convenience functionalities like obtaining the last created run.


ANONYMOUS#

Equivalent to ANONYMOUS_API_TOKEN (see below).


ANONYMOUS_API_TOKEN#

API token for anonymous logging.

You can use this value for the api_token parameter of the init methods.

Example

# Start a run as an anonymous user
run = neptune.init_run(
    api_token=neptune.ANONYMOUS_API_TOKEN,
    project="common/quickstarts",
)

get_last_run()#

Deprecated

This method is deprecated. Support of it will be removed with the upcoming release of neptune-client 1.0.0.

Fetches the last created run object.

Returns

run object last created by the global neptune object.

Example

import neptune.new as neptune

# Crate a new tracked run
neptune.init_run(name="A new approach", source_files="**/*.py")

# Oops - we didn't assign it to a "run" variable.

# Not a problem! We've got you covered:
run = neptune.get_last_run()

get_project()#

Deprecated

This method is deprecated. Support of it will be removed with the upcoming release of neptune-client 1.0.0.

Use neptune.init_project(mode="read-only") instead.

Initialize a connection to a project in read-only mode.

Parameters

Name Type Default Description
name str, optional None Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.
api_token str, optional None User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

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

proxies dict, optional None Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.

Returns

Project object that can be used to fetch metadata from the project, like project-level metadata or data from the runs table.

Example

import neptune.new as neptune

# Fetch project "jackie/named-entity-recognition"
project = neptune.get_project(name="jackie/named-entity-recognition")

# Fetch the metadata of all runs as a pandas DataFrame
runs_table_df = project.fetch_runs_table().to_pandas()

init()#

Deprecated

This method is deprecated. Support of it will be removed with the upcoming release of neptune-client 1.0.0.

Use neptune.init_run() instead.

Convenience alias for init_run().


init_model()#

Initializes a Model object from an existing or new model.

You can use this method to create a new model from code or to perform actions on existing models.

Parameters

Name      Type Default     Description
with_id str, optional None The Neptune identifier of an existing model to resume, such as "CLS-PRE". The identifier is stored in the object's sys/id field. If omitted or None is passed, a new model is created.
name str, optional "Untitled" A custom name for the model version.
key str, optional None Key for the new model. Required when creating a new model version.
  • Used together with the project key to form the model identifier.
  • Must be uppercase and unique within the workspace.
project str, optional None Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.
api_token str, optional None User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

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

mode str, optional async Connection mode in which the tracking will work. Possible values are async, sync, offline, read-only, and debug.

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.

flush_period float, optional 5 In asynchronous (default) connection mode, how often Neptune should trigger disk flushing (in seconds).
proxies dict, optional None Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.

Returns

Model object that is used to manage the model and log metadata to it.

Examples

import neptune.new as neptune

# Create a new model
model = neptune.init_model(key="PRE")

# You can provide the project parameter as an environment variable
# or directly in the init_model function
model = neptune.init_model(key="PRE", project="workspace-name/project-name")

# When creating a model, you can give it a name
model = neptune.init_model(key="PRE", name="Pre-trained model")

# Initialize existing model with identifier "CLS-PRE"
model = neptune.init_model(with_id="CLS-PRE")

# To prevent modifications when connecting to an existing model,
# you can connect in read-only mode
model = neptune.init_model(with_id="CLS-PRE", mode="read-only")

init_model_version()#

Initializes a ModelVersion object from an existing or new model version.

You can use this method to create a new model version from code or to perform actions on existing model versions.

Parameters

Name      Type Default     Description
with_id str, optional None The Neptune identifier of an existing model version to resume, such as "CLS-PRE-3". The identifier is stored in the object's sys/id field. If omitted or None is passed, a new model version is created.
name str, optional "Untitled" A custom name for the model version.
model str, optional None Identifier of the model for which the new version should be created. Required when creating a new model version. The identifier is stored in the model's sys/id field.
project str, optional None Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.
api_token str, optional None User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

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

mode str, optional async Connection mode in which the tracking will work. Possible values are async, sync, offline, read-only, and debug.

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.

flush_period float, optional 5 In asynchronous (default) connection mode, how often Neptune should trigger disk flushing (in seconds).
proxies dict, optional None Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.

Returns

ModelVersion object that is used to manage the model version and log metadata to it.

Examples

import neptune.new as neptune

# Create a new model version for a model with identifier "CLS-PRE"
model_version = neptune.init_model_version(model="CLS-PRE")

# You can provide the project parameter as an environment variable
# or directly in the init_model_version() method
model_version = neptune.init_model_version(
    model="CLS-PRE",
    project="ml-team/classification",
)

# Initialize model version object with an existing model version
# with identifier "CLS-PRE-12"
model_version = neptune.init_model(with_id="CLS-PRE-12")

# To prevent modifications when connecting to an existing model version,
# you can connect in read-only mode
model_version = neptune.init_model(with_id="CLS-PRE-12", mode="read-only")

init_project()#

Starts a connection to an existing Neptune project. You can use it to retrieve information about runs, models, and model versions within the project.

You can also log (and fetch) metadata common to the whole project, such as information about datasets, links to documents, or key project metrics.

Parameters

Name      Type Default     Description
name str, optional None Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.
api_token str, optional None User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

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

mode str, optional async Connection mode in which the tracking will work. Possible values are async, sync, offline, read-only, and debug.

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.

flush_period float, optional 5 In asynchronous (default) connection mode, how often Neptune should trigger disk flushing (in seconds).
proxies dict, optional None Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.

Returns

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

Example

import neptune.new as neptune

# Connect to the project "classification" in the workspace "ml-team"
project = neptune.init_project(name="ml-team/classification")

# Connect to a project in read-only mode
project = neptune.init_project(
    name="ml-team/classification",
    mode="read-only",
)

init_run()#

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

Since all parameters are optional, the minimal invocation is:

run = neptune.init_run()

Parameters

Name       Type Default     Description
project str, optional None Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.
api_token str, optional None User's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

Set to neptune.ANONYMOUS_API_TOKEN to log metadata anonymously.

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

with_id str, optional None The Neptune identifier of an existing run to resume, such as "CLS-11". The identifier is stored in the object's sys/id field. If omitted or None is passed, a new tracked run is created.
custom_run_id str, optional None A unique identifier that can be used to log metadata to a single run from multiple locations. Max length: 32 characters. If None and the NEPTUNE_CUSTOM_RUN_ID environment variable is set, Neptune will use that as the custom_run_id value. For details, see Setting custom run ID.
mode str, optional async Connection mode in which the tracking will work. Possible values are async, sync, offline, read-only, and debug.

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.

name str, optional "Untitled" Editable name of the run. Is displayed in the run details and can be added as a column in the runs table.
description str, optional "" Editable description of the run. Is displayed in the run details and can be added as a column in the runs table.
tags list, optional [] Must be a list of str which represent the tags for the run. You can edit them after run is created, either in the run details or runs table.
source_files list or str, optional None

List of source files to be uploaded. Must be list of str or a single str. Uploaded sources are displayed in the Source code section of the run.

If None is 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 Python 3.5 and later). For details, see the glob library.

capture_stdout Boolean, optional True Whether to log the standard output stream. Is logged in the monitoring namespace.
capture_stderr Boolean, optional True Whether to log the standard error stream. Is logged in the monitoring namespace.
capture_hardware_metrics Boolean, optional True Whether to track hardware consumption (CPU, GPU, memory utilization). Logged in the monitoring namespace.
fail_on_exception Boolean, optional True If an uncaught exception occurs, whether to set run's Failed state to True.
monitoring_namespace str, optional "monitoring" Namespace inside which all monitoring logs will be stored.
flush_period float, optional 5 In asynchronous (default) connection mode, how often Neptune should trigger disk flushing (in seconds).
proxies dict, optional None Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.
capture_traceback Boolean, optional True In case of an exception, whether to log the traceback of the run.

Returns

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

Examples

import neptune.new as neptune

run = neptune.init_run()

# Create a run with a custom name
run = neptune.init_run(name="first-pytorch-ever")

# Create a run with a name and description, and no sources files uploaded
run = neptune.init_run(
    name="neural-net-mnist",
    description="neural net trained on MNIST",
    source_files=[],
)

# 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"],
)