`neptune`#

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

Import statement

import neptune

`init_model()`#

Initializes a Model object from an existing or new model.

You can use this function 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`, `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.

Deprecated model parameter

The model parameter has been changed to with_id as of neptune-client 0.16.7.

Returns

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

Examples

Create a new model:

import neptune

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 function 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`, `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.

Deprecated version parameter

The version parameter has been changed to with_id as of neptune-client 0.16.7.

Returns

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

Examples

Create a new model version for a model with identifier "CLS-PRE":

import neptune

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() function:

model_version = neptune.init_model_version(
    model="CLS-PRE",
    project="ml-team/classification",
)

Initialize 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
`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`, `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.

Deprecated name parameter

The name parameter has been changed to project as of neptune-client 0.16.16.

Returns

Project object 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")

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 runs table.

Since all parameters are optional, the minimal invocation is:

import neptune

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.
`git_ref`	`GitRef`	`None`	`GitRef` object containing information about the Git repository path. If `None`, Neptune looks for a repository in the path of the script that is executed. To specify a different location, set to `GitRef(repository_path="path/to/repo")`. To turn off Git tracking for the run, set to `GitRef.DISABLED`. For examples, see Logging Git info.

Deprecated run parameter

The run parameter has been changed to with_id as of neptune-client 0.16.7.

Returns

run object 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="first-pytorch-ever")

Create a run with a name and description, and no sources files or Git info uploaded:

from neptune.types import GitRef

run = neptune.init_run(
    name="neural-net-mnist",
    description="neural net trained on MNIST",
    source_files=[],
    git_ref=GitRef.DISABLED,
)

Resume an existing run, to continue logging to it:

import neptune

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

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

How do I find the ID?

The Neptune ID is a unique identifier for the object. It's displayed in the Details view and in the leftmost column of the table views.

The ID is stored in the system namespace. You can obtain it with object["sys/id"].fetch(). For example:

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

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

import neptune

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

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

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,
)

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
)

How do I save my credentials as environment variables?

Set your Neptune API token and full project name to the NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables, respectively.

For example:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...6Lc" # (1)!

On Windows, the command is set instead of export.

export NEPTUNE_PROJECT="ml-team/classification" # (1)!

On Windows, the command is set instead of export.

Finding your credentials:

API token: In the top-right corner of the Neptune app, click your avatar and select Get your API token.
Project: Your full project name has the form workspace-name/project-name. To copy the name, navigate to your project → Settings → Properties.

If you're working in 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 the api_token argument of the init functions.

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 the neptune package to initialize Neptune, you can also import and use the anonymous API token separately.

NeptuneLogger and PyTorch Lightning

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=...
)

Deprecated#

This part of the API is deprecated and will be removed as of neptune 1.0.

`get_last_run()`#

Deprecated

This function is deprecated. As of neptune 1.0 it's no longer supported.

Fetches the last created run object.

Returns

run object last created by the global neptune object.

Example

import 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 function is deprecated. As of neptune 1.0 it's no longer supported.

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

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

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.

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

Fetch project "jackie/named-entity-recognition":

import neptune

project = neptune.get_project(project="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 function is deprecated. As of neptune 1.0 it's no longer supported.

Use neptune.init_run() instead.

Convenience alias for init_run().

`ANONYMOUS`#

Deprecated

This constant is deprecated. As of neptune 1.0 it's no longer supported.

Equivalent to ANONYMOUS_API_TOKEN.

neptune#

init_model()#

init_model_version()#

init_project()#

init_run()#

ANONYMOUS_API_TOKEN#

Deprecated#

get_last_run()#

get_project()#

init()#

ANONYMOUS#

`neptune`#

`init_model()`#

`init_model_version()`#

`init_project()`#

`init_run()`#

`ANONYMOUS_API_TOKEN`#

`get_last_run()`#

`get_project()`#

`init()`#

`ANONYMOUS`#