Connection modes

You can track data to Neptune using one of the four connection modes:

  • asynchronous (default)

  • synchronous

  • offline

  • debug

You can select mode by passing 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 got restarted (e.g. spot instances) or in case there were some 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.


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


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.


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