Connection modes

You can connect to Neptune using one of the five connection modes:

You can select mode by providing mode parameter to the neptune.init function:

import as neptune
# A default connection mode is the asynchronous mode
# Other possible values are "async", "sync", "offline", "debug"
run = neptune.init(name="My new run", mode=CONNECTION_MODE)

Asynchronous (default)

All tracking calls (like log(), assign(), save()) are non-blocking. The tracked data is temporarily stored on the local disk and synchronized with the Neptune server in the background by a separate synchronization thread.

We recommend using Neptune with persistent disks to be able to restore tracked data in case your machine restarts (e.g. spot instances) or in case of connectivity issues with Neptune servers.

Synchronization thread is a python thread that is spawned in the background by Neptune client to send tracked data to Neptune server.

Disk flushing

Neptune triggers disk flushing:

  • Every 5 seconds (this period is configurable, see neptune.init()).

  • When you invoke run.wait() .

  • At the end of the run (destruction of the Run context).

Error handling

Tracking calls in asynchronous mode do not throw exceptions related to connectivity or metadata consistency issues (more in the distributed computing section). Issues related to connectivity or metadata consistency issues will be printed to stderr.

Connectivity issues

When you use asynchronous (default) connection mode and there is a problem with the connection to Neptune servers (e.g. caused by Internet connectivity issues), the Neptune Client Library will continue to locally track your metadata and will continuously try to re-establish connection with Neptune servers.

Once your run is finished, if the connection has not been reestablished, Neptune will continue trying for another 5 minutes. After this period the process will end. All the unsuccessful tracking calls are stored on the local disk. The unsynchronized metadata from the local disk can be uploaded later via Neptune CLI (Command Line Interface) neptune synccommand.


Tracking calls return only after the Neptune server responds that the data was stored.

import as neptune
run = neptune.init(name="My new run", mode="sync")

In this mode tracking methods throw exceptions in case of connectivity issues or issues related to the run's local representation consistency (see distributed computing section).

Neptune will retry each request for 60 seconds before throwing the exception.


In this mode, no connection to Neptune servers is established. Instead, all the tracked metadata is stored on the local disk and can be uploaded to Neptune servers manually via neptune sync command.

import as neptune
run = neptune.init(name="My new run", mode="offline")

In this mode, you cannot fetch data from Neptune servers. All the fetching calls with throw exception OfflineModeFetchException.

Uploading offline data

Whether you experience connectivity issues or you are working in offline mode your data is stored safely locally. You can use Neptune CLI (Command Line Interface) to check the synchronization status and synchronize data with Neptune servers.

Neptune stores the data in a .neptune folder in the current working directory.

Checking synchronization status

You can list unsynchronized runs by using status command:

# List unsynchronized runs in the current directory
neptune status
# List unsynchronized runs in the given path
neptune status --path PATH_TO_DIRECTORY
# Access status command help and examples
neptune status --help

Synchronizing data with Neptune servers

Synchronize local data with Neptune servers with sync command:

# Synchronize all runs in the current directory
neptune sync
# Synchronize all runs in the given path
neptune sync --path PATH_TO_DIRECTORY
# Synchronize only runs NPT-42 and NPT-43
neptune sync -run workspace/project/NPT-42 -run workspace/project/NPT-43
# Synchronise all runs in the current directory
# sending offline runs to project "workspace/project"
neptune sync -p workspace/project
# Synchronize the offline run a1561719-b425-4000-a65a-b5efb044d6bb
# to project "workspace/project"
neptune sync -p workspace/project -run offline/a1561719-b425-4000-a65a-b5efb044d6bb
# Access sync command help and examples
python -m sync --help

Runs created in offline mode need a specified project where to be uploaded. You can either specify it through --project parameter or by setting NEPTUNE_PROJECT environment variable.


A read-only mode useful when you need only to fetch your run's metadata. For example, you are connecting to Neptune to perform a specific analysis on your run's metadata that is not possible inside Neptune. In this mode:

  • No write operation is possible. Any write-like operation will be ignored.

  • No metadata is sent to Neptune. In particular stdout and stderr are not captured, and no hardware metrics are being sent.

  • The run never switches to Active status, because of a read-only connection.

import as neptune
# Connecting to run wih SUN-2 identifier
run = neptune.init(run="SUN-2", mode="read-only")

Read-only mode is only possible when resuming the run.


Debug mode can come in handy when you are debugging your code and would like to not pollute your project. In this mode, no calls are made to Neptune servers, regardless of what happens in the code. In contrast to Offline mode, all data are stored only in memory.

import as neptune
run = neptune.init(name="My new run", mode="debug")

What's next?