Skip to content

Run#

Representation of all metadata of a tracked experiment.

Initialization#

Initialize with the init_run() function or the class constructor.

import neptune

run = neptune.init_run()
from neptune import Run

run = Run()
If Neptune can't find your project name or API token

As a best practice, you should save your Neptune API token and project name as environment variables:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8"
export NEPTUNE_PROJECT="ml-team/classification"

Alternatively, you can pass the information when using a function that takes api_token and project as arguments:

run = neptune.init_run( # (1)!
    api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8",  # your token here
    project="ml-team/classification",  # your full project name here
)
  1. Also works for init_model(), init_model_version(), init_project(), and integrations that create Neptune runs underneath the hood, such as NeptuneLogger or NeptuneCallback.

  2. API token: In the bottom-left corner, expand the user menu and select Get my API token.

  3. Project name: You can copy the path from the project details ( Edit project details).

If you haven't registered, you can log anonymously to a public project:

api_token=neptune.ANONYMOUS_API_TOKEN
project="common/quickstarts"

Make sure not to publish sensitive data through your code!

With the run object, you can:

  • Log metadata in a structure of your choosing.
  • Download run metadata to your local machine.
  • Delete metadata from the run.

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

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 Your Neptune API token (or a service account's API token). If None, the value of the NEPTUNE_API_TOKEN environment variable is used.

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: 36 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 Set custom run ID.
mode str, optional async Connection mode in which the logging 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" Custom name for the run. You can use it as a human-readable ID and add it as a column in the runs table (sys/name).
description str, optional "" Editable description of the run. You can add it as a column in the runs table (sys/description).
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 information 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 (seconds) In asynchronous (default) connection mode, how often Neptune should trigger disk flushing.
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 or Boolean 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 or False.

For examples, see Logging Git info.
dependencies str, optional None Tracks environment requirements. If you pass "infer" to this argument, Neptune logs dependencies installed in the current environment. You can also pass a path to your dependency file directly. If left empty, no dependency file is uploaded.
async_lag_callback NeptuneObjectCallback, optional None Custom callback function which is called if the lag between a queued operation and its synchronization with the server exceeds the duration defined by async_lag_threshold. The callback should take a Run object as the argument and can contain any custom code, such as calling stop() on the object.

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.

async_lag_threshold float, optional 1800.0 (seconds) Duration between the queueing and synchronization of an operation. If a lag callback (default callback enabled via environment variable or custom callback passed to the async_lag_callback argument) is enabled, the callback is called when this duration is exceeded.
async_no_progress_callback NeptuneObjectCallback, optional None Custom callback function which is called if there has been no synchronization progress whatsoever for the duration defined by async_no_progress_threshold. The callback should take a Run object as the argument and can contain any custom code, such as calling stop() on the object.

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.

async_no_progress_threshold float, optional 300.0 (seconds) For how long there has been no synchronization progress. If a no-progress callback (default callback enabled via environment variable or custom callback passed to the async_no_progress_callback argument) is enabled, the callback is called when this duration is exceeded.

Returns

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

Examples

Initialize a new run with optional arguments
from neptune import Run

run = Run(
    name="serious-cherry",
    description="Write a longer description here.",
    tags=["pytorch", "test"],
    source_files=["training_with_pytorch.py", "net.py"],
    dependencies="infer",
)
Initialize existing run with idenfitier CLS-16, to resume logging
from neptune import Run

run = Run(with_id="CLS-16")
Initialize existing run in read-only mode, to avoid modifying or adding data
from neptune import Run

run = Run(with_id="CLS-16", mode="read-only")

Field lookup: []#

Accesses the field of a run through a dict-like lookup: run[field_path].

Returns

The returned type depends on the field type and whether a field is stored under the given path.

Path Example Returns
Field exists - The returned type matches the type of the field
Field does not exist - Handler object
Path is namespace and has field

Path: "train"

Field "train/acc" exists

Namespace handler object

Examples

When you assign some metadata to a new path in the run, it creates a field of a certain type.

Create new Float field
run["parameters/momentum"] = 0.9

You can assign a new value of the same type to the field. Unless the logging method is iterative, this will overwrite the previous value.

Update the value of the field
run["parameters/momentum"] = 0.8

Assignment: =#

Convenience alias for assign().


assign()#

Assign values to multiple fields from a dictionary. For example, you can use this method to quickly log all the parameters of a run.

Parameters

Name Type Default Description
value dict None A dictionary with values to assign, where keys (str) become the paths of the fields. The dictionary can be nested, in which case the path will be a combination of all keys.
wait Boolean, optional False By default, logged metadata is sent to the server in the background. With this option set to True, Neptune first sends all data before executing the call. See Connection modes.

Examples

run["parameters/max_epochs"].assign(10)
run["parameters/optimizer"].assign("Adam") # (1)!

# Assign multiple fields from a dictionary
run.assign({"parameters": {"max_epochs": 10, "optimizer": "Adam"}}) # (2)!
  1. Equivalent to:

    run["parameters/max_epochs"] = 10
    run["parameters/optimizer"] = "Adam"
    
  2. Equivalent to:

    params = {"max_epochs": 10, "optimizer": "Adam"}
    run["parameters"] = params
    

del#

Completely removes the field or namespace and all associated metadata stored under the path.

If you need to free up storage or reduce the number of fields, use del to remove unneeded metadata that takes up space, such as notebook training checkpoints.

See also: pop().

Examples

params = {"max_epochs": 10, "optimizer": "Adam"}
run["model/parameters"] = params
Delete field with path "model/parameters/optimizer"
del run["model/parameters/optimizer"]
Delete the whole namespace
del run["model/parameters"]

If you have unneeded checkpoints but want to keep the runs, you can delete just the checkpoints:

# Resume an existing run
run = neptune.init_run(with_id="CLS-47")

# Delete the namespace "training/checkpoints" with the training checkpoint
del run["training/checkpoints"]

exists()#

Checks if there is a field or namespace under the specified path.

Info

This method checks the local representation of the run. If the field was created by another process or the metadata has not reached the Neptune servers, it may not be possible to fetch. In this case you can:

  • Call sync() on the run to synchronize the local representation with the server.
  • Call wait() on the run to wait for all logging calls to finish.

Parameters

Name Type Default Description
path str - Path to check for the existence of a field or namespace

Examples

# Resume run with identifier CLS-34
run = neptune.init_run(with_id="CLS-34")

# If the training is complete, remove training checkpoints if present
if run.exists("model/checkpoints") and run["train/finished"].fetch() == True:
    del run["model/checkpoints"]

Info

When working in asynchronous (default) mode, the metadata you track may not be immediately available to fetch from the server, even if it appears in the local representation.

To work around this, you can call wait() on the run.

run["learning_rate"] = 0.1

# The path exists in the local representation
if run.exists("learning_rate"):
    # However, the tracking call may have not reached Neptune servers yet
    run["learning_rate"].fetch()  # Error: the field does not exist

run.wait()

fetch()#

Fetches the values of all single-value fields (that are not of type File) as a dictionary.

The result preserves the hierarchical structure of the model metadata. You can use this method, for example, to quickly retrieve run parameters.

Returns

dict containing the values of all non-File single-value fields.

Example

# Resume run with identifier CLS-123
run = neptune.init_run(project="ml-team/classification", with_id="CLS-123")

# Fetch the run parameters
params = run["model/params"].fetch()

get_structure()#

Returns the metadata structure of a run in the form of a dictionary.

This method can be used to traverse the metadata structure programmatically when using Neptune in automated workflows.

See also: print_structure().

The returned object is a shallow copy of the run's internal structure. Any modifications to it may result in logging malfunction.

Returns

dict with the run metadata structure.

Example

>>> run.get_structure()
{'data': {'val': <neptune.attributes.atoms.artifact.Artifact object at 0x0000020374B822C0>}, 'f1_score': <neptune.attributes.atoms.float.Float object at 0x0000020374B81A50>, 'monitoring': {'cpu': <neptune.attributes.series.float_series.FloatSeries object at 0x0000020374B81A80>, ... }}

get_url()#

Returns a direct link to the run in Neptune. The same link is printed in the console once the run has been initialized.

Returns

str with the URL of the run in Neptune.

Example

>>> import neptune
>>> run = neptune.init_run(with_id="NER-35")
>>> run.get_url()
https://app.neptune.ai/jackie/named-entity-recognition/e/NER-35

pop()#

Completely removes the field or namespace and all associated metadata stored under the path.

See also del.

Parameters

Name Type Default Description
path str - Path of the field or namespace to be removed.
wait Boolean, optional False By default, logged metadata is sent to the server in the background. With this option set to True, Neptune first sends all data before executing the call. See Connection modes.

Examples

run["parameters/learninggg_rata"] = 0.3
# Let's correct the misspelled field

# Delete the field along with its data
run.pop("parameters/learninggg_rata")

# Reassign to correct field
run["parameters/learning_rate"] = 0.3
# Training finished
run["trained_model"].upload("model.pt")

# Previously logged "model_checkpoint" is no longer needed
run.pop("model_checkpoint")

You can invoke pop() directly on fields and namespaces:

# The following line
run.pop("parameters/learninggg_rata")
# is equiavlent to this line
run["parameters/learninggg_rata"].pop()
# and this line
run["parameters"].pop("learninggg_rata")
Batch-delete the whole namespace
run["parameters"].pop()

Pretty-prints the structure of the run metadata. Paths are ordered lexicographically and the structure is colored.

See also: get_structure().

Example

>>> import neptune
>>> run = neptune.init_run(with_id="NER-35")
>>> run.print_structure()
'data':
    'val': Artifact
'f1_score': Float
'monitoring':
    'cpu': FloatSeries
    'gpu': FloatSeries
    'gpu_memory': FloatSeries
    'memory': FloatSeries
    'stderr': StringSeries
    'stdout': StringSeries
'parameters':
    'learning_rate': Float
    'optimizer': String
...

stop()#

Stops the connection to Neptune and synchronizes all data.

Info

Every active run keeps a connection open with Neptune, monitors hardware usage, etc. If you are performing multiple training jobs from one script, one after the other, stop each run once tracking is no longer needed.

You can also use context managers. Neptune will automatically call stop() when exiting the run context.

Warning

Always call stop() in interactive environments, such as a Python interpreter or Jupyter notebook. The connection to Neptune is not stopped when the cell has finished executing, but rather when the entire notebook stops.

If you're running a script, the connection is stopped automatically when the script finishes executing. However, it's a best practice to call stop() when the connection is no longer needed.

Parameters

Name Type Default Description
seconds int or float, optional None Wait for the specified time for all logging calls to finish before stopping the connection. If None, wait for all logging calls to finish.

Examples

If you are creating tracked runs from a Python script, Neptune stops the run automatically when the script finishes executing.

import neptune

run = neptune.init_run()

[...]  # Your training or monitoring code

# stop() is automatically called at the end for every Neptune object

Stopping multiple tracked runs manually at the end of a training job:

for config in configs:
    run = neptune.init_run()
    [...]  # Your training or monitoring code
    run.stop()

Using with statement and context manager:

for config in configs:
    with neptune.init_run() as run:
        [...]  # Your training or monitoring code
        # stop() is automatically called when code execution exits the with statement

sync()#

Synchronizes the local representation of the run with Neptune servers.

Parameters

Name Type Default Description
wait Boolean, optional False By default, logged metadata is sent to the server in the background. With this option set to True, Neptune first sends all data before executing the call. See Connection modes.

Example

# Connect to a run from Worker #3
worker_id = 3
run = neptune.init_run(
    with_id="DIST-43",
    monitoring_namespace=f"monitoring/{worker_id}",
)

# Try to access logs that were created in the meantime by Worker #2
worker_2_status = run["status/2"].fetch()
# Error if this field was created after this script starts

run.sync() # Synchronize local representation with Neptune servers
worker_2_status = run["status/2"].fetch() # No error

wait()#

Wait for all the logging calls to finish.

Parameters

Name Type Default Description
disk_only Boolean, optional False If True, the process will wait only for the data to be saved locally from memory, but will not wait for it to reach Neptune servers.

Deprecated#

get_run_url()#

Deprecated

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

Use get_url() instead.