Skip to content

Run API reference#

Representation of all metadata of a tracked experiment.

Initialization
import neptune.new as neptune

# Create new run
run = neptune.init_run()

# Initialize existing run with ID "CLS-16", to resume logging
run = neptune.init_run(with_id="CLS-16")

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.

Field lookup: []#

You can access the field of a run through a dict-like field lookup: run[field_path].

This way, you can

  1. track metadata:

    run["params/max_epochs"] = 20
    for epoch in range(20):
        run["epoch/acc"].log(epoch_accuracy)
    
  2. fetch already tracked metadata, such as retrieving parameters when resuming a run or downloading metadata for a custom analysis:

    learning_rate = run["params/max_epochs"].fetch()
    acc_df = run["epoch/acc"].fetch_values()
    

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

import neptune.new as neptune

run = neptune.init_run()

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

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

# Error - it's no longer possible to store a File under a Float field
run["parameters/momentum"].upload("sample_data.csv")  # Error

# Create new Series fields
run["train/logs"].log("Experimenting Day 1:")
run["train/acc"].log(0.01)

# Continue logging to existing Series fields
run["train/logs"].log("I embark on a journey")
run["train/acc"].log(0.02)

# If you access a namespace handler, you can interact with it
# in a similar way to the run object
params_ns = run["parameters"]
params_ns["lr"] = 0.3 # Stores 0.3 under path "parameters/lr"

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

import neptune.new as neptune

run = neptune.init_run()

# Assign multiple fields from a dictionary
params = {"max_epochs": 10, "optimizer": "Adam"}
run["parameters"] = params

# The above is equivalent to
run.assign({"parameters": {"max_epochs": 10, "optimizer": "Adam"}})

# You can also assign parameters one by one
run["parameters/max_epochs"] = 10
run["parameters/optimizer"] = "Adam"

# The above is equivalent to
run["parameters/max_epochs"].assign(10)
run["parameters/optimizer"].assign("Adam")

# Dictionaries can be nested
params = {"train": {"max_epochs": 10}}
run["parameters"] = params
# This logs the value 10 under the path "parameters/train/max_epochs"

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

import neptune.new as neptune

run = neptune.init_run()

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

# Delete field with path "model/parameters/optimizer"
del run["model/parameters/optimizer"]

# You can also delete the whole namespace
del run["model/parameters"]

Freeing up space by deleting 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 tracking calls to finish.

Parameters

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

Examples

import neptune.new as neptune

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

# If the training is complete remove training checkpoints if they are there
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.

import neptune.new as neptune

run = neptune.init_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 values of all non-File Atom fields as a dictionary.

The result preserves the hierarchical structure of the run metadata, but contains only Atom fields that are not of the type File. You can use this method, for example, to quickly retrieve run parameters.

Returns

dict containing the values of all non-File Atom fields.

Example

import neptune.new as neptune

# 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().

Caution

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

Returns

dict with the run metadata structure.

Example

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

get_run_url()#

Deprecated method. Use get_url() instead.


get_url()#

Returns a direct link to the run in Neptune. Ihe 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.new as 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, tracked 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

import neptune.new as neptune

run = neptune.init_run()

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

# "model_checkpoint" is a File field
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")

# You can also 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.new as 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.

Caution

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 tracking calls to finish before stopping the connection. If None, wait for all tracking 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.new as 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, tracked 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

import neptune.new as neptune

# Connect to a run from Worker #3
worker_id = 3
run = neptune.init_run(
    with_id="DIST-43",
    monitoring_namespace="monitoring/{}".format(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 tracking 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.
Back to top